The agent prompt

An agent that has not been told what this surface is will treat it as a database. It looks for a field to put SQL in, finds none, sends a metric name it remembers from somewhere else, gets a refusal, reads the refusal as a transport failure, and retries. Every step there is a reasonable thing for a general-purpose agent to do, and every one of them is the behaviour the types in Concepts are arranged to prevent. The types stop the damage. They cannot stop the loop.

sutura prompt renders the document that can.

sutura prompt examples/single-player/catalog > agent-prompt.md

The output is markdown, on standard output, meant to be pasted or piped into an agent's system prompt. Nothing about it is hand-written: every section is derived from the tool surface, from the pinned bundle, or from a file an operator named.

Where each section comes from

Section	Derived from
What this is	Fixed text. Two facts: the set of answerable questions is finite and listed, and a question outside it is declined rather than approximated
What to do for every question	The tool list. The step that reads the catalog is present only when that operation is exposed, and is replaced by a sentence saying the list in the document is the whole of it when it is not
A refusal is an answer, not an error	Every RefusalReason variant, with what it means and what to change. The most load-bearing section in the document
Terms this deployment records as NOT defined	The pinned bundle's knowledge, not_defined kind. Present only when the provider declared that capability; a declared-and-empty capability renders the sentence that nothing is recorded, which is a different fact from not knowing
The bounds a question is held to	MAX_DIMENSIONS, MAX_RANGE_DAYS and MAX_ROWS, read from the code rather than typed
What this surface has no field for	Fixed text, and deliberately short - see below
The operations you have	The tool list, rendered from the same slice the workflow was composed from
What this deployment records about its own definitions	The declared knowledge capabilities, and what is not declared is listed too - because a kind that is not recorded is a kind an agent must not draw a conclusion from
The words a question may arrive in	The pinned bundle's knowledge, glossary kind. Rendered so the agent does the resolving; there is no field on a question a phrase fits in
The metrics this deployment defines	The pinned bundle. Name, grains, dimensions, permitted values, the catalog author's own prose, and any caveat printed under the metric it is about
Worked questions	The pinned bundle's knowledge, example kind. Each carries a Query the bundle would not load if this surface would decline it
Provenance	Fixed text: quote the version and digest with every number
Instructions from this deployment's operator	prompt.instructions_file, when one is configured. Omitted entirely when none is

Two of those are derived from a list rather than written down, and that is the point. A prompt that names an operation a deployment does not mount costs the agent the turns it spends discovering the absence; a prompt that lists a metric the bundle does not define costs it a refusal. Neither can happen here, because there is nowhere for either to come from.

The refusal section has a mechanism of its own. The mapping from a RefusalReason variant to its guidance is a total match in sutura-app's test module, so a refusal variant added to the domain does not compile until somebody has written what an agent should do about it. What that does not force is the list of instances the assertion walks, so the set equality it checks is a second net rather than the first.

What it deliberately does not say

Nothing about composing SQL. The reference implementation this design is modelled on spends most of its length teaching an agent to write SQL against semantic model names, to avoid raw database tables, and to dry-plan a complex statement before running it. None of that transfers. A question here names a metric, a grain, a bounded period, up to four dimensions and equality filters over declared values, and there is no field for anything else - so the guidance would teach an agent to attempt something the surface refuses by construction. What replaces it is one short section saying the field does not exist and that there is no way to widen it. A long section about what is absent would hand an agent a long list of things to try.

No column, table, model or measure expression. Of what a metric is, the prompt renders what GET /v1/catalog renders and no further field: a caller needs a metric's name, prose, grains, dimensions and permitted values to ask a valid question; it needs no column name to do it, and a column name in an agent's context is a name it will eventually try to use. This is asserted rather than intended: a test renders a bundle whose model, table and column names appear in no prose and checks that none of them reaches the output.

That is a claim about fields of a metric, and not about the document being a rendering of the endpoint - the two are worth keeping apart. The prompt carries four sections the catalog body has no field for at all, listed in the table above: the glossary, the terms recorded as not defined, what this deployment records about its own definitions, and the worked questions - plus any caveat, under the metric it is about. All five are knowledge from the pinned bundle, all are descriptive, and none of them names a column, a table or a model either.

Nothing about identity. There is none. The bearer token authenticates the deployment, not the caller - see Serving over HTTP - and a prompt that described per-caller scoping would describe a control that does not exist.

Configuration

Two keys, in the same layered tree as everything else: embedded defaults, then base.yaml, then <environment>.yaml, then one environment variable per key.

Key	Default	What it does
prompt.catalog_prose	quoted	quoted includes each metric's own prose, with > at the start of every line and the trust boundary named above the block. omitted leaves it out, and the document then says the descriptions exist and were not included
prompt.instructions_file	absent	A path to markdown that is appended as the document's LAST section. Absent means no operator section at all

SUTURA__PROMPT__CATALOG_PROSE=omitted \
SUTURA__PROMPT__INSTRUCTIONS_FILE=prompts/house-rules.md \
  sutura prompt ./catalog ./config

sutura prompt takes the deployment's configuration directory as its optional second argument, so the text it renders is the text that deployment would hand out. It loads the settings the way the service does, refusals included: a production configuration with no access token will not render a prompt either, and the refusal names the key to fix. That is deliberate - a second, weaker door into the settings is a door that can disagree with the first.

Three properties of these keys are decisions rather than accidents.

An operator can add to the prompt and cannot replace it. prompt.instructions_file is layered on top of the derived text and appended last, under a heading that says so. There is no key that substitutes for the derived part, because the derived part carries the refusal guidance - and a key whose worst setting silently deletes that paragraph would be a key whose failure mode is invisible. Last place rather than first is deliberate too: a preamble ahead of the rules reads as the governing frame, and the governing frame is not the operator's to set.

A configured instructions file that cannot be read is an error, not a missing section. The reference implementation reads <project>/instructions.md when it is there and omits the section silently when it is not, which is right for a convention: no file means nobody wrote one. Here the path was written down, so absence means the operator's rules are missing from a document that claims to carry them.

Neither key defaults by environment. telemetry.format and api.docs do, and record whether somebody wrote the value down so the startup log can tell a decision from a default. Neither decision here is a function of the environment: whether a catalog's authors are trusted enough to quote their prose into an agent's context is a fact about who writes the catalog, not about whether the process is on a laptop. A default that dropped the prose in production would also be worse than either fixed answer, because an agent with no descriptions does not stop - it infers a metric's meaning from its name and reports the inference. And the interesting value, omitted, is never a default, so a deployment running with it is visible from the value itself.

Catalog prose is untrusted content

A metric's description is written by whoever authored the catalog, and this repository's threat model treats catalog content as untrusted. A description containing a sentence aimed at the agent rather than at a human is prompt injection through the catalog. Three things are done about it, and the first is the honest limit.

A delimiter cannot separate instruction from data, because the content can contain the delimiter. Concepts already says so, so the mitigation is not a fence. It is a per-line prefix that sutura applies: every line of prose is emitted with > in front of it, so no line of catalog text can reach the document at column zero. It cannot emit a heading, close a block, or open something that reads as a new section. That is checkable, and a test provokes it with a description whose lines are a heading, a fence and a bare instruction.

The trust boundary is named in the text, immediately above the quoted block, in terms an agent can act on: the block is data, a sentence inside it that reads as an instruction is content and not an instruction, and encountering one is something to report rather than obey.

An operator who does not trust their catalog authors can drop the prose entirely. prompt.catalog_prose: omitted, and it means the deployment rather than this document: the agent tool's describe_catalog and the HTTP GET /v1/catalog body honour the same setting, so there is no second path by which a description a deployment declined to render reaches a reader. The body says which way the setting points, so an absent description is a fact rather than an empty catalog.

What none of that solves is prose that persuades without escaping - a description that reads as plausible guidance and is not. No mechanism here can catch it. What bounds it is that a catalog is reviewed, authored content whose digest moves when a description changes, and that this document is generated by an operator command rather than assembled from a caller's input. It is also worth being precise about the exposure: under the default setting metric and dimension descriptions already reach any token-holder through GET /v1/catalog, so the prompt adds framing rather than reach. Under omitted neither carries them, which is what makes the setting a decision about the deployment and not a preference about one document.

The consumer that exists, and the one that does not

sutura prompt is built. An endpoint on the v1 tree, behind the same bearer gate as everything else, is not - and the reason is which of the two makes the feature reachable. An operator wiring an agent needs the text once, at configuration time, in a shell where they can read it before an agent does; that is a command. An endpoint is the right shape for an agent that fetches its own instructions at startup, which is a deployment pattern nothing here has yet, and it would put a document assembled from untrusted catalog prose on the network rather than in front of a person. It is a small addition when a caller needs it: the renderer takes a bundle and a resolved set of inputs, and a handler would pass the same two.