--- title: "12. Elicitation Declarations" description: "MCP Description specification v0.9.0-rc.3 — 12. Elicitation Declarations." source: "https://mcpdesc.org/docs/specification/0.9.0-rc.3/elicitation/" --- ### 12.1 Purpose and Placement An Elicitation Declaration documents that fulfillment of a Tool, Resource, Resource Template, or Prompt may require additional interaction with the user through the MCP client. Tool, Resource, Resource Template, and Prompt Objects MAY contain an `elicitations` array of Elicitation Declaration Objects. [](/docs/rules/0.9.0-rc.3/mcpdesc/tool-members#required-by "This requirement is part of rule: mcpdesc.tool.members") The array MUST contain at least one declaration when present. A Resource Template declaration applies to `resources/read` operations on concrete Resource URIs produced from that template; it does not describe elicitation during template discovery. An Elicitation Declaration describes durable server behavior rather than the protocol-specific wire exchange. It does not assert that every fulfillment triggers the interaction or that every client can fulfill it. A conditional or optional Elicitation Declaration MUST NOT by itself be interpreted as an unconditional `clientRequirements.elicitation` capability requirement. ### 12.2 Elicitation Declaration Object [](/docs/rules/0.9.0-rc.3/mcpdesc/elicitation-members#required-by "This requirement is part of rule: mcpdesc.elicitation.members") | Property | Type | Required | Description | | ---------------- | -------------------------- | ----------- | ----------------------------------------------------------------- | | name | string | **Yes** | Stable local declaration name. | | mode | "form" or "url" | **Yes** | Canonical elicitation mode. | | message | string | **Yes** | Representative user-facing explanation of the interaction. | | when | string | No | Human-readable description of when the interaction may occur. | | requestedSchema | object or Reference Object | Conditional | Inline or reusable restricted MCP form-response schema. | | url | string (URI) | No | Static URL when known at description-authoring time. | | onDecline | string | No | Human-readable expected behavior after explicit decline. | | onCancel | string | No | Human-readable expected behavior after cancellation or dismissal. | | protocolVersions | array | No | MCP protocol versions to which this declaration applies. | [](/docs/rules/0.9.0-rc.3/mcpdesc/elicitation-members#required-by "This requirement is part of rule: mcpdesc.elicitation.members") `name` MUST match `^[A-Za-z0-9._-]+$`. [](/docs/rules/0.9.0-rc.3/mcpdesc/elicitation-name-unique#required-by "This requirement is part of rule: mcpdesc.elicitation.name-unique") Names are case-sensitive and MUST be unique within the containing primitive declaration. [](/docs/rules/0.9.0-rc.3/mcpdesc/elicitation-members#required-by "This requirement is part of rule: mcpdesc.elicitation.members") `message` MUST be non-empty. It documents the explanation a user should receive and MAY be representative or default wording when runtime context changes the exact text. Runtime wording SHOULD NOT materially contradict the documented purpose, but mcpdesc does not require byte-for-byte equality. [](/docs/rules/0.9.0-rc.3/mcpdesc/elicitation-members#required-by "This requirement is part of rule: mcpdesc.elicitation.members") `when`, `onDecline`, and `onCancel`, when present, MUST be non-empty descriptive contract documentation. They are not executable expressions, client instructions, or statically provable guarantees. Although applicable MCP protocol versions permit omission of runtime `mode` for form elicitation, mcpdesc requires explicit `mode` to provide one canonical static representation. ### 12.3 Form Mode For `mode: "form"`: * [](/docs/rules/0.9.0-rc.3/mcpdesc/elicitation-members#required-by "This requirement is part of rule: mcpdesc.elicitation.members") `requestedSchema` is REQUIRED; * [](/docs/rules/0.9.0-rc.3/mcpdesc/elicitation-members#required-by "This requirement is part of rule: mcpdesc.elicitation.members") `url` MUST NOT appear; and * [](/docs/rules/0.9.0-rc.3/mcp/elicitation-form-schema-members#required-by "This requirement is part of rule: mcp.elicitation.form-schema.members") `requestedSchema` MUST describe an object with only the property schemas allowed by every applicable MCP protocol version. `requestedSchema` MAY be a Reference Object targeting the `schemas` component namespace. [](/docs/rules/0.9.0-rc.3/mcpdesc/components-references#required-by "This requirement is part of rule: mcpdesc.components.references") The referenced schema MUST be resolved before applying every restricted-vocabulary and effective-protocol-scope requirement in this section. The schema is limited to a flat object whose properties use MCP elicitation primitive schemas. Nested objects and arrays other than MCP-supported multi-select enumeration forms are invalid. Unsupported keywords and unsupported string formats are invalid. MCP 2025-06-18 supports string, number, integer, boolean, and legacy string-enum property schemas. It permits string length constraints and the `email`, `uri`, `date`, and `date-time` formats, numeric bounds, boolean defaults, and optional `enumNames` corresponding to enum values. It does not define `$schema`, defaults for strings, numbers, or enums, titled `oneOf` enums, or multi-select arrays. MCP 2025-11-25 and MCP 2026-07-28 additionally support defaults for all primitive types, standard titled single-select enums, titled and untitled multi-select enums, and the legacy `enumNames` form. [](/docs/rules/0.9.0-rc.3/mcp/elicitation-form-schema-protocol-shape#required-by "This requirement is part of rule: mcp.elicitation.form-schema.protocol-shape") Validators MUST apply the vocabulary of every applicable protocol version. [](/docs/rules/0.9.0-rc.3/mcpdesc/elicitation-form-schema-consistency#required-by "This requirement is part of rule: mcpdesc.elicitation.form-schema.consistency") A `required` entry MUST name a property declared in `properties`. [](/docs/rules/0.9.0-rc.3/mcpdesc/elicitation-form-schema-consistency#required-by "This requirement is part of rule: mcpdesc.elicitation.form-schema.consistency") `enumNames`, when present, MUST contain one display name for every enum value. [](/docs/rules/0.9.0-rc.3/mcpdesc/elicitation-form-schema-consistency#required-by "This requirement is part of rule: mcpdesc.elicitation.form-schema.consistency") An enum default MUST be one of its declared values, and every multi-select default value MUST occur in its declared item choices. [](/docs/rules/0.9.0-rc.3/mcpdesc/elicitation-form-schema-consistency#required-by "This requirement is part of rule: mcpdesc.elicitation.form-schema.consistency") Minimum constraints MUST NOT exceed their corresponding maximum constraints. ### 12.4 URL Mode For `mode: "url"`: * [](/docs/rules/0.9.0-rc.3/mcpdesc/elicitation-members#required-by "This requirement is part of rule: mcpdesc.elicitation.members") `requestedSchema` MUST NOT appear; * [](/docs/rules/0.9.0-rc.3/mcpdesc/elicitation-members#required-by "This requirement is part of rule: mcpdesc.elicitation.members") `url`, when present, MUST be a syntactically valid URI; and * omission of `url` means the concrete URL is generated or selected at runtime. A runtime URL-mode elicitation still supplies every field required by the applicable MCP protocol version. Omission in mcpdesc does not make the runtime URL optional. Validation of `url` is syntax-only. Validators and other consumers MUST NOT retrieve, prefetch, dereference, or otherwise access it while processing a description. A conforming declaration does not assert that the target is currently available, trusted, immutable, controlled by the server, or suitable for automatic navigation. ### 12.5 Protocol Applicability An omitted Elicitation Declaration `protocolVersions` inherits the effective scope of its containing primitive. [](/docs/rules/0.9.0-rc.3/mcpdesc/protocol-scope-consistency#required-by "This requirement is part of rule: mcpdesc.protocol-scope.consistency") An explicit scope MUST be non-empty and MUST be a subset of that containing scope. Complete protocol-version-specific validation begins with MCP 2025-06-18: * MCP 2025-06-18 supports form mode; * MCP 2025-11-25 supports form and URL modes; and * MCP 2026-07-28 supports form and URL modes. [](/docs/rules/0.9.0-rc.3/mcp/elicitation-protocol-version#required-by "This requirement is part of rule: mcp.elicitation.protocol-version") A declaration spanning multiple protocol versions MUST satisfy every applicable protocol version. Authors MUST split materially incompatible declarations into disjoint scopes. MCP 2024-11-05 and MCP 2025-03-26 retain the legacy compatibility treatment in Section 3.5\. [](/docs/rules/0.9.0-rc.3/mcpdesc/legacy-protocol-validation-scope#required-by "This requirement is part of rule: mcpdesc.legacy-protocol.validation-scope") Validators apply structural and selected sound checks, issue the existing incomplete-validation diagnostic, and MUST NOT report complete MCP semantic conformance. ### 12.6 Static-Description Boundary The applicable MCP protocol version remains authoritative for execution. MCP Description does not model whether elicitation uses a server-initiated request or Multi Round-Trip Requests, nor lifecycle messages, identifiers, request state, retries, correlation, capability negotiation, or transport behavior. Static primitive `clientRequirements` may record an unconditional minimum elicitation capability without defining any of that choreography. A mock, gateway, documentation tool, or client MAY use a declaration to render its message, collect a form response matching `requestedSchema`, or present a known URL. The declaration alone does not define when a mock triggers the interaction, how it selects among declarations, how responses modify state, or which final primitive result follows. Elicitation Declarations are distinct from named primitive examples. Tool Examples pair a complete invocation with a completed Tool Result, Tool `interactionExamples` add ordered semantic client-input steps for one Tool invocation, and Resource Examples contain completed read results. None of these models preserve JSON-RPC envelopes, MRTR request state, retries, timing, or a general executable workflow language. The applicable MCP elicitation specification remains authoritative for runtime security and privacy requirements. MCP Description validation does not inspect or certify runtime behavior, privacy compliance, or security conformance and defines no sensitive-field diagnostic. ### 12.7 Example ```yaml tools: - name: assign_issue description: Assign an issue to a teammate. inputSchema: type: object properties: issue: type: integer assignee: type: string required: [issue] additionalProperties: false elicitations: - name: choose_assignee mode: form when: No assignee was supplied. message: Who should own this issue? requestedSchema: type: object properties: assignee: type: string title: Assignee required: [assignee] onDecline: Leave the issue unassigned. onCancel: Abort without modifying the issue. ```