What is PromptArgument?
A PromptArgument defines a single named slot within a Prompt's parameter contract. When a client calls `prompts/get`, it passes a map of argument values keyed by these names; the server then interpolates them into the final message sequence before returning. This makes PromptArgument the boundary between the host's runtime context — user input, selected text, cursor position — and the static template stored on the server. In the MCP message flow, PromptArguments appear first in `prompts/list` responses (inside each `Prompt.arguments` array) so that hosts can render a UI before the user commits to calling the prompt. Only at call time does the host pass actual values. The `required` flag tells the host whether to block invocation if a value is missing; servers should validate this on receipt and return an error rather than silently interpolating an empty string. PromptArgument has intentionally stayed a thin shape throughout the spec's evolution: `name`, an optional human-readable `title`, an optional `description` for tooltip copy, and the optional `required` boolean. There is no `type` field and no JSON Schema constraint — all values are plain strings. If you need validated, structured input (numbers, enums, nested objects), reach for a Tool instead. This constraint keeps prompt invocation simple for chat-oriented hosts that render a plain text input per argument slot.
When to use
When a Prompt has variable inputs the user provides at call time.
When NOT to use
For complex nested objects — those belong in a Tool.
Notes
required defaults to false, not true
The spec leaves `required` optional and implicitly false when absent. Hosts that build argument forms must therefore treat any argument without an explicit `required: true` as optional and allow the user to skip it. Servers that actually need the argument should always set the flag explicitly rather than relying on the description field to communicate obligation.
title vs name for UI rendering
The `name` field is the machine key passed in the `arguments` map at call time; `title` is display copy for host UIs. If `title` is omitted, well-behaved hosts fall back to rendering `name` directly. Use `title` to present friendlier labels ("Output language" instead of `output_lang`) without breaking the wire key that your template logic references.
No type system — strings only
PromptArgument carries no `type` or `schema` field, so every argument value is an untyped string on the wire. Servers that need numeric or boolean semantics must parse and validate values themselves. If validation complexity grows, this is a signal to migrate the interaction to a Tool with a proper JSON Schema input definition.
Argument map must match names exactly
The `arguments` object in a `prompts/get` request is a plain string-to-string map keyed by the `name` field. Passing an unrecognised key is not an error per spec, but missing a required key should produce an `InvalidParams` error. In practice, mismatched casing or a renamed argument between `prompts/list` and `prompts/get` is a common source of silent empty-slot bugs in production servers.
Listing arguments enables capability negotiation
Clients can inspect `Prompt.arguments` from `prompts/list` before ever calling `prompts/get`. This lets a host suppress a prompt from its UI entirely if it cannot satisfy a required argument given its current context — for example, a code-editor host hiding prompts that require a `selected_text` argument when no selection exists. Designing argument names to reflect their semantic source (not just their template role) makes this negotiation more reliable.
Fields
| Field | Type | Required | Purpose |
|---|---|---|---|
| name | string | yes | Argument name. |
| title | string? | no | Display name. |
| description | string? | no | What this argument should contain. |
| required | boolean? | no | Whether the argument must be provided. |
Examples
Required argument
{ "name": "destination", "required": true, "description": "Where the user wants to travel." }Common mistakes
❌ Forgetting required:true on essential arguments
✅ Mark mandatory arguments explicitly so clients can validate before calling.