Prompts

Read these first

• Architecture

What you will know

• Expose a server-provided prompt and invoke it from a client

  A prompt is a server-supplied template the user explicitly invokes, not something the model triggers.

• Trace a prompt invocation from client selection through server response, including argument validation and error handling

  The trace should make failures attributable to discovery, schema handling, transport, rendering, or the client’s presentation layer.

• Design a prompt that takes arguments

  Defaults, constraints, and escaping determine whether a reusable template remains safe when values come from users or other context.

• Reproduce a client that incorrectly exposes a prompt as model-callable, then patch the boundary

  Conflating prompts with tools can let an agent initiate workflows that were intended to require an explicit user action.

• Compare a prompt, resource, and tool implementation for one workflow and justify the selected primitive using user initiation, side effects, and reuse

  The wrong primitive produces either awkward manual UX or unintended authority, especially when a read-only template is given executable semantics.

Chapters

1. 1

   User-controlled prompts

   The single property separating a prompt from a tool is who is permitted to start it: a tool is model-controlled and can fire mid-turn on the model's judgement, a prompt is user-controlled and exists as an explicit human action. The same triage capability registered each way produces opposite symptoms — a postmortem page nobody asked for, carrying an impact figure of 4,200 sessions that was wrong by a factor of three, against eleven invocations in six weeks all by the two people who wrote it. Exposing it both ways is not free coverage, because the security property collapses to the weaker of the two.

   Read chapter
2. 2

   prompts/get and the name field

   Invoking a prompt returns a list of messages, each with a role and a typed content block, for the host to place into the live conversation — not a string, and not a tool result. Discovery hands back two strings per prompt, name for the wire and title for the screen, so a host that sends the display title where the identifier belongs produces -32602 'prompt not found' for a prompt that plainly lists. Five named stages make each failure attributable, including the quietest one: 6 of 412 invocations in a month returned a well-formed postmortem with an empty Timeline because a data fetch was swallowed.

   Read chapter
3. 3

   Prompt argument declaration and validation

   Each entry in a prompt's arguments list carries a name, a title, a description and a required flag, and nothing else — no type, no enum, no pattern, no default. An argument meant to hold one of three values has no way to say so, which is why a month of one prompt's traffic contained 47 distinct values for a three-value argument across 1,842 invocations. Completion is the only affordance a client can offer and it is a suggestion rather than a gate, so the permitted set is enforced where prompts/get arrives, and adding a required argument to a shipped prompt is not a deployable change on its own.

   Read chapter
4. 4

   Prompt injection through interpolation

   A template that splices review_text straight into a paragraph ending 'follow the instructions above exactly' has handed authorship of its instructions to whoever wrote the review. Delimiting the span with escaped markers, labelling it as quoted material and giving it its own message turn are the structural fixes; telling the model to ignore embedded instructions is one instruction competing with another, adjudicated by the same model. In a 100-case red-team pass those measures took compliance from 31 to 4, and to 1 once the tail enumerated permitted output — a rate reduction, not a control.

   Read chapter
5. 5

   Flattening prompts into the tools array

   Some hosts convert every connected server's prompts into model-callable tools, with argsToSchema turning the four-field argument declarations into string properties and a locally invented readOnlyHint suppressing confirmation. The chain that follows is short: an untrusted document in the context induces a call to run_release_checklist, whose returned messages instruct the model to call three tools in order, and a release happens. The boundary to restore is a missing dispatcher arm rather than a filter, and per-tool confirmation does not rescue the design when 78% of users have enabled allow-for-this-session within ten minutes.

   Read chapter
6. 6

   Decomposing a workflow across three primitives

   Weekly release notes need a structure and an explicit start, a house style document, and a live list of merged PRs — a prompt, a resource and a tool respectively. Collapsing that into one prompt returning everything inline froze the content at invocation, cost roughly 8,000 tokens of style guide plus 6,000 of PR bodies on every run, and smuggled the consequential step in as a closing sentence the model obeyed. Decide by initiation, side effects and reuse, put the irreversible part behind an action a person takes, and keep an answer ready for hosts that surface prompts badly.

   Read chapter