# Agent & Prompt Specification Turns the job an agent must do into the specification someone implements: what it can do, with which tools, and what it does when it must not proceed. ## Deliverable One Markdown document, `agent-specification.md`, in the structure set out under **Output** below. It takes the output of **AI Use-Case Feasibility Assessment** and feeds **Evaluation Set & Metric Design**. ## Required inputs - **The job the agent must do** — the task, who it serves, and the action its output changes. - **The systems it may touch** — the tools, data stores and endpoints it is permitted to call, and the permission each one runs under. - **The escalation route** — the named role that receives a case when the agent must not continue. If any is absent, report it as missing and stop before writing scope. An agent specified without its permitted systems describes capabilities it may not have. ## Optional inputs - Existing prompts, system messages or agent configurations for the same task - The output schema a downstream system already expects - Style, tone or format rules the organisation applies to generated text - The content the agent will read that originates outside the organisation - Rate, cost or latency limits the runtime imposes - Records of how people perform this task today Every optional input that is absent becomes an entry under **Open questions**. A tool, a schema field or a limit is never invented to fill one. ## Execution **1 — State the scope and the non-scope.** One paragraph of what the agent does; a list of the adjacent things it does not do and must decline. The non-scope is the harder half and is written alongside the scope: an agent with no stated boundary acquires one by accident, in production. **2 — Enumerate the tools.** For each: what it does, what the agent must have established before calling it, what it returns, what it changes, and whether the change can be reversed. Every tool that writes, sends or spends carries the confirmation the agent must obtain before calling it, and from whom. **3 — Trace every capability to a tool.** Take each thing the specification claims the agent can do and name the tool that performs it. A capability with no tool behind it is removed. It is not described as a future capability and it is not left in with a caveat, because a reader implements what the document says. **4 — Fix the output schema.** The fields the agent returns, the type of each, which are required, and what an unknown or empty value looks like in each. Prose is a field, not the response. The system that consumes the answer parses the schema, and a schema written afterwards is written around whatever the model happened to produce. **5 — Write the grounding rules.** What the agent may assert on its own, what it must attribute to a source it retrieved, and what it must not state at all. Specify what it does when retrieved sources disagree and when it retrieves nothing: both need a defined response, and in neither case is that response the model's own recollection. **6 — Define refusal and escalation.** The conditions under which the agent stops: outside scope, insufficient evidence, an irreversible action without confirmation, or a request it must not serve. For each: what it says, what it records, and the named role it hands to. **7 — Handle untrusted content.** Tool results, retrieved documents and user-supplied files carry text that nobody in the organisation wrote. Specify that such text is data and never instruction, how it is delimited when it reaches the model, which tools are unavailable while it is in context, and what the agent does when it contains something addressed to it. ## Output `agent-specification.md`, in this order: - **1. Purpose and date** — the job, who it serves, and when this was written - **2. Scope** — what the agent does - **3. Non-scope** — what it declines, and what it says when it declines - **4. Tools** — per tool: purpose, preconditions, what it returns, side effects, reversibility, confirmation required - **5. Capability trace** — each capability against the tool that performs it - **6. Output schema** — field, type, required or optional, and the empty form - **7. Grounding rules** — assertable, attributable, forbidden; behaviour on conflict and on no result - **8. Refusal and escalation** — condition, response, record, named role - **9. Untrusted content** — sources, delimiting, restricted tools, response to embedded instructions - **10. Open questions** — what is undecided, what it blocks, who decides ## Validation The specification is ready when all of these hold: - Every capability in section 5 names a tool that exists in section 4 - Every tool that changes state says whether the change is reversible and what confirmation precedes it - Section 6 defines an empty form for every optional field - Section 7 states behaviour for both conflicting sources and no result - Every escalation in section 8 names a role, not a queue - Section 9 covers every source of external text named in section 4 Fail the run if a capability has no tool, or if a state-changing tool has no confirmation rule. ## Failure handling - **No tool list supplied** — produce sections 1 to 3 and 10, and report that scope cannot be fixed without the permitted systems. An agent's scope is the set of its tools. - **A capability with no tool** — remove it from the specification and record it in section 10 as a request for a tool. Do not describe behaviour the agent cannot perform. - **No escalation route** — write sections 1 to 7, mark section 8 `UNASSIGNED` and record the missing route as blocking. An agent that cannot hand a case off will proceed with it instead. - **Contradictory requirements** — record both, name both sources, and raise the conflict in section 10 as a decision for a named person. Do not merge them into a rule that satisfies neither. - **Partial material** — specify every section the material supports, mark the rest `INCOMPLETE — pending `, and deliver.