--- title: "9. Tools" description: "MCP Description specification v0.8.0 — 9. Tools." source: "https://mcpdesc.org/docs/specification/0.8.0/tools/" --- ## 9\. Tools The `tools` array declares the tools exposed by the MCP server. Each tool represents a server-side function that clients can invoke. ### 9.1 Tool Object | Property | Type | Required | Description | | ------------------- | --------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | protocolVersions | array | No | MCP revisions to which this declaration applies. | | name | string | **Yes** | Programmatic tool name (identifier). | | title | string | No | Human-readable display name for UI contexts. Since MCP 2025-06-18. | | description | string | No | Human-readable tool description. | | inputSchema | object or Reference Object | **Yes** | Inline or reusable JSON Schema whose root describes an object containing tool input parameters. | | outputSchema | object or Reference Object | No | Inline or reusable JSON Schema for structured tool output. Since MCP 2025-06-18. | | annotations | [Tool Annotations Object](#95-tool-annotations) | No | Behavioral hints. Since MCP 2025-03-26. | | execution | [Execution Object](#96-execution-object) | No | Execution properties. MCP 2025-11-25 only. | | examples | map | No | Named complete Tool invocation/result pairs. | | interactionExamples | map | No | Named ordered semantic client-input scenarios attached to one Tool invocation. | | icons | non-empty array | No | Icons for UI display. Since MCP 2025-11-25. | | tags | non-empty array | No | Categorization tags. When a root-level tags array is present, values MUST reference declared tag names (see [Section 13.3](/docs/specification/0.8.0/tags#133-tag-references)). | | elicitations | non-empty array | No | Additional user interactions that MAY be required while fulfilling the Tool (see [Section 12](/docs/specification/0.8.0/elicitation#12-elicitation-declarations)). | | deprecated | boolean | No | Whether the tool is deprecated. | | \_meta | object | No | Literal MCP metadata on the Tool declaration, subject to [Section 3.5](/docs/specification/0.8.0/document-structure#35-mcp-%5Fmeta). Since MCP 2025-06-18. | | security | Security Requirement Array | No | Primitive security override. | | clientRequirements | [Client Capability Requirements Object](/docs/specification/0.8.0/capabilities#85-primitive-client-capability-requirements) | No | Unconditional minimum client capabilities required for tools/call; does not apply to tools/list. | ### 9.2 Input and Output Schemas Every Tool MUST contain `inputSchema`. Absence MUST NOT be interpreted as evidence that the Tool accepts no arguments. The schema root MUST describe an object. `inputSchema` and `outputSchema` MAY be Reference Objects targeting the `schemas` component namespace. Resolution MUST occur before applying every inline schema rule in this section, including root shape, dialect, protocol applicability, `x-mcp-header`, and example compatibility. See [Section 17](/docs/specification/0.8.0/components#17-reusable-components-and-local-references). A closed no-parameter Tool SHOULD use `{ "type": "object", "additionalProperties": false }`. An open unspecified-parameter Tool may use `{ "type": "object" }`, but this is NOT RECOMMENDED because it gives little validation or guidance. A declared-parameter schema uses `properties` and, when undeclared properties must be rejected, `additionalProperties: false`. The `outputSchema` property, when present, MUST be a valid JSON Schema object describing the tool’s structured output. For MCP 2025-11-25 and MCP 2026-07-28, it defaults to JSON Schema 2020-12 when no explicit `$schema` is provided. For MCP 2025-11-25 and MCP 2026-07-28, both schemas MAY include an explicit `$schema` property to declare the JSON Schema dialect. Earlier revisions do not define that property on Tool schemas. For MCP 2026-07-28, validators MUST accept the applicable JSON Schema 2020-12 vocabulary, including references, composition, and conditionals, plus MCP-defined annotations where valid. Earlier views MUST be checked according to their applicable MCP schema rules. For MCP 2025-11-25 and MCP 2026-07-28, every embedded Tool schema MUST be valid under its declared or default dialect. Both revisions default to JSON Schema 2020-12\. A validator MUST reject a schema whose declared dialect it does not support. The supported revisions before MCP 2025-11-25 define an object-rooted Tool schema shape but do not state an embedded-schema dialect default. For those revisions, validators MUST enforce the applicable shape without inferring a dialect solely from the enclosing generated MCP schema. `properties`, when present, MUST be an object whose values are objects, and `required`, when present, MUST be an array of strings. Other keywords MUST be preserved and MUST NOT be rejected solely by applying an inferred meta-schema. An mcpdesc validator MUST NOT automatically retrieve an external `$ref` target from a network. It MAY resolve external references from an explicitly supplied trusted local catalogue or an explicitly enabled resolver that follows the applicable MCP security guidance. If a target remains unavailable, the `$ref` MUST be preserved and its presence alone MUST NOT make the containing MCP Description invalid. The validator SHOULD warn that complete embedded-schema validation was not possible and MUST NOT report a weakened or partial validation as complete. Consumers that require executable schema certainty SHOULD require resolution or treat this warning as an error. Authors SHOULD prefer self-contained Tool schemas using local `$defs`. Before MCP 2026-07-28, `outputSchema` MUST declare an object root. MCP 2026-07-28 permits any valid JSON Schema root for `outputSchema`. MCP 2026-07-28 `inputSchema` properties MAY use `x-mcp-header` to map an input to an HTTP header. The annotation value MUST be a non-empty HTTP field-name token and MUST be unique case-insensitively within that `inputSchema`. It is valid only on a `string`, `integer`, or `boolean` property that is statically reachable from the schema root through `properties` chains. It MUST NOT be used on a property reached through arrays, composition, conditionals, or `$ref`. ### 9.3 Named Tool Examples A Tool Object MAY contain `examples`, a map from a local example name to an inline Tool Example Object or a Reference Object targeting `#/components/toolExamples/`. When present, the map MUST contain at least one entry. Each name MUST match `^[A-Za-z0-9._-]+$`; names are case-sensitive, scoped to the containing Tool declaration, and serve as both human-meaningful labels and stable local selection names. Entry order is not semantically significant. A referenced example MUST be resolved before applying every contextual requirement of the containing Tool and effective protocol scope. A Tool Example Object contains these core properties and MAY carry `x-*` specification extensions: | Property | Type | Required | Description | | -------- | ------ | -------- | ----------------------------------------------------------------------------------- | | input | object | **Yes** | Complete params.arguments value from a tools/call request. | | result | object | **Yes** | Complete applicable completed Tool Result payload, excluding the JSON-RPC envelope. | The Tool Example Object MUST NOT contain other additional properties. In particular, 0.8.0 does not define `summary`, `description`, or `externalValue`. `input` MUST be an object and MUST validate against the containing Tool’s `inputSchema` under every applicable protocol revision’s schema rules. A no-argument invocation MUST use `input: {}`. Schema-invalid values belong in negative test material, not conforming Tool Examples. `result` MUST contain `content` and MUST have the completed Tool Result shape defined by every applicable protocol revision. For MCP 2026-07-28 it MUST contain `resultType: "complete"`; earlier revisions MUST NOT contain `resultType`. Task, input-required, streaming, progress, JSON-RPC envelope, and JSON-RPC protocol-error forms are not Tool Examples. Content blocks MAY use any text, image, audio, embedded-resource, or resource-link form supported by every applicable revision. Revision-supported `_meta` on the completed result, content blocks, and embedded Resource Contents is literal illustrative metadata governed by [Section 3.5](/docs/specification/0.8.0/document-structure#35-mcp-%5Fmeta). It is not a schema or a request-metadata declaration. In MCP 2026-07-28, a result example MAY use `io.modelcontextprotocol/serverInfo` with an MCP Implementation value; request-only and notification-only reserved keys are invalid in these represented contexts. A successful result MUST omit `isError` or set it to `false`. It MAY contain `structuredContent` only in revisions that support that field. If the Tool declares `outputSchema`, a successful result MUST contain `structuredContent`, which MUST validate against that schema under the applicable schema rules. Unstructured `content` remains required when `structuredContent` is present. If the Tool has no `outputSchema`, a successful result MAY contain revision-supported `structuredContent`, but mcpdesc makes no schema-compatibility claim for that value. A Tool execution-error result MUST set `isError` to `true`, MUST contain unstructured `content`, and MUST NOT contain `structuredContent`. `outputSchema` does not validate error content. JSON-RPC protocol errors and transport or intermediary failures that prevent a Tool Result are outside this model. Example compatibility is a semantic conformance requirement. For revisions before MCP 2025-11-25, validators MUST enforce constraints they can interpret without inventing an embedded-schema dialect, SHOULD warn when complete compatibility validation is impossible, and MUST NOT report incomplete validation as complete. An unresolved external `$ref` follows the policy in Section 9.2: validators preserve the schema and example, do not retrieve the target automatically, and warn that compatibility validation is incomplete. A schema-incompatible example is an error whenever complete evaluation is possible. Tool `examples` and JSON Schema `examples` annotations are independent. Schema annotations remain suitable for anonymous values at an instance location; Tool Examples pair named complete invocations with completed results. Producers MUST NOT infer an author-supplied Tool Example by combining unrelated schema annotations. Tool Examples are illustrative and non-exhaustive. They do not alter schemas, annotations, security requirements, side effects, or runtime behavior, and they do not guarantee that a live server returns a shown result. Documentation tooling SHOULD preserve names and input/result pairing. Mock or contract-test tooling MAY permit explicit selection by name but MUST NOT execute a live Tool or reproduce declared side effects merely because an example exists. Selection without an explicit name MUST use a deterministic documented policy and MUST NOT be presented as a prediction of live behavior. Examples are untrusted descriptive content. Authors MUST NOT include secrets and SHOULD use conspicuously fictitious values. Consumers MUST validate values, render content as data, and apply appropriate size and evaluation limits. They MUST NOT treat examples as authorization, proof of behavior, or safe executable instructions. Tool Examples are MCP Description metadata, not fields of the MCP Tool type. Projection to an MCP `tools/list` Tool value MUST omit `examples` unless an independently specified MCP extension defines a destination. MCP Description round-tripping and protocol-version projection MUST preserve each selected Tool declaration’s example map and MUST NOT merge maps from disjoint variants with the same Tool name. ### 9.4 Tool Interaction Examples A Tool Object MAY contain `interactionExamples`, a non-empty map from a local scenario name to a Tool Interaction Example Object. Each name MUST match `^[A-Za-z0-9._-]+$`, is case-sensitive, and is scoped to the containing Tool declaration. The map is declaration-local: 0.8.0 defines no `components` namespace for interaction scenarios. Tool `interactionExamples` are separate from completed Tool `examples`. A producer MUST NOT place an incomplete workflow, semantic interaction step, or non-terminal Tool result in the completed `examples` map. A Tool Interaction Example Object contains these core properties and MAY carry `x-*` specification extensions: | Property | Type | Required | Description | | -------- | --------------------------------------------- | -------- | ------------------------------------------------------------------------ | | input | object | **Yes** | Complete initial tools/call.params.arguments object. | | steps | non-empty array | **Yes** | Ordered semantic client-input exchanges for this illustrated invocation. | | result | object | **Yes** | Terminal completed Tool Result payload, excluding the JSON-RPC envelope. | `input` follows the same schema-compatibility rules as Tool Example `input`. `result` follows the same completed success and execution-error rules as Tool Example `result`. The scenario is illustrative and non-exhaustive: it asserts only that the shown steps occur in the displayed order in this example. It does not define branching, retries, correlation IDs, task state, transport framing, timing, or behavior for responses not shown. Every Tool Interaction Step Object MUST contain `type`, `request`, and `response`. MCP Description 0.8.0 defines three step kinds: | type | Request payload | Response payload | | ----------- | ---------------------------------------- | --------------------------------------------------------------- | | elicitation | Canonical elicitation request fields | Canonical elicitation response action and optional form content | | sampling | Native sampling/createMessage parameters | Native completed sampling result | | roots | Empty object | Native ordered roots result object | Steps MAY carry `x-*` specification extensions and MUST NOT contain other additional fields except those defined for their step kind. A step is semantic MCP Description metadata, not a native MCP wire object. An implementation MUST NOT serialize a Tool Interaction Step directly onto an MCP connection. An `elicitation` step MAY contain `declaration`, naming an Elicitation Declaration on the same Tool. When present, the request mode and the request schema or known URL MUST be compatible with that declaration after local reference resolution. For `mode: "form"`, an accepted response MUST contain `content` conforming to the request schema; declined and cancelled responses MUST NOT contain `content`. For `mode: "url"`, the response MUST omit `content`. A `sampling` step request uses the native `sampling/createMessage` parameter field names and constraints of every MCP revision in the containing Tool’s effective protocol scope, excluding JSON-RPC, transport, task, and MRTR framing. This includes required `messages` and `maxTokens`, and MAY include revision-supported model preferences, system prompt, context inclusion, stop sequences, temperature, metadata, and Tool-related fields. Its response uses the native completed sampling result field names and constraints of every applicable revision, excluding JSON-RPC and task framing. A `roots` step request is an empty object. Its response contains the ordered native `roots` declarations returned by the client for this illustration. Roots are descriptive input only; they do not authorize filesystem access. The containing Tool’s effective protocol scope controls validation. Every represented semantic field MUST be valid in every applicable revision. A Tool spanning materially incompatible interaction shapes MUST be split into disjoint protocol-scoped variants. `interactionExamples` themselves do not carry `protocolVersions`. Tool `interactionExamples` do not add server capabilities, `clientRequirements`, or Elicitation Declarations. Validators SHOULD warn when a scenario contradicts an explicit primitive `clientRequirements` declaration, but MUST NOT infer a requirement when the Tool declares none. Tool Interaction Examples are MCP Description metadata, not fields of the MCP Tool type. Projection to an MCP `tools/list` Tool value MUST omit `interactionExamples` unless an independently specified MCP extension defines a destination. Effective Protocol View projection MUST preserve the selected Tool declaration’s scenario map without combining disjoint variants. Merge tooling MUST NOT concatenate step arrays or guess how to combine unequal same-name scenarios. Interaction scenarios are untrusted descriptive content. Authors MUST use fictitious or sanitized values and MUST NOT include secrets, credentials, opaque runtime request state, task handles, or live session identifiers. Consumers MUST treat URLs, prompts, roots, and generated content as data and MUST NOT navigate, execute, or trust them merely because a scenario exists. ### 9.5 Protocol Variants and Security Tools with the same `name` MUST have pairwise-disjoint effective protocol scopes. Projection therefore yields at most one declaration for that name. An omitted scope covers all root revisions and overlaps every scoped Tool with the same name. Tool `security` describes statically known authorization required to call the Tool and replaces inherited transport or root security in full. Tool `clientRequirements` applies only to invocation through `tools/call`. It does not state that a client needs those capabilities to discover the Tool through `tools/list`. ### 9.6 Tool Annotations Tool Annotations provide hints about Tool behavior. They are distinct from the Resource Annotations used by Resources, Resource Templates, and content blocks (see [Section 10.3](/docs/specification/0.8.0/resources#103-resource-annotations)). A Tool `annotations` object MUST use the fields and semantics in this section; Resource Annotation fields such as `audience`, `priority`, and `lastModified` do not acquire those semantics when placed on a Tool. All Tool Annotation properties are advisory. They are not guaranteed to describe Tool behavior faithfully, including `title`. Clients MUST treat Tool Annotations from untrusted servers as untrusted and MUST NOT make Tool-use decisions based on them. | Property | Type | Default | Description | | --------------- | ------- | ------- | ------------------------------------------------------------ | | title | string | — | Human-readable title for the tool | | readOnlyHint | boolean | false | Tool does not modify its environment | | destructiveHint | boolean | true | Tool may perform destructive updates | | idempotentHint | boolean | false | Repeated calls with same arguments have no additional effect | | openWorldHint | boolean | true | Tool may interact with external entities | The Tool Annotations object allows additional properties for forward compatibility. Consumers MUST preserve unrecognized properties where round-tripping is required and MUST NOT assign them the semantics of Resource Annotations. ### 9.7 Execution Object | Property | Type | Default | Description | | ----------- | ------ | ----------- | ------------------------------------------------------------------------------------------ | | taskSupport | string | "forbidden" | Whether the tool supports task-augmented execution: "forbidden", "optional", or "required" | ### 9.8 Example ```json { "tools": [ { "name": "analyze_game", "title": "Analyze Chess Game", "description": "Analyze a chess game from PGN notation and return evaluation scores", "inputSchema": { "type": "object", "properties": { "pgn": { "type": "string", "description": "Game in Portable Game Notation (PGN) format" }, "depth": { "type": "integer", "description": "Analysis depth in half-moves", "minimum": 1, "maximum": 40 } }, "required": ["pgn"] }, "outputSchema": { "type": "object", "properties": { "evaluation": { "type": "number", "description": "Centipawn evaluation" }, "best_move": { "type": "string", "description": "Best move in algebraic notation" }, "blunders": { "type": "array", "items": { "type": "object", "properties": { "move_number": { "type": "integer" }, "move": { "type": "string" }, "evaluation_loss": { "type": "number" } } } } } }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true }, "tags": ["analysis", "chess"] }, { "name": "get_player_rating", "title": "Get Player Rating", "description": "Get the current Elo rating and rating history for a chess player", "inputSchema": { "type": "object", "properties": { "player_id": { "type": "string", "description": "Unique player identifier" }, "rating_type": { "type": "string", "enum": ["classical", "rapid", "blitz", "bullet"], "description": "Type of rating to retrieve" } }, "required": ["player_id"] }, "annotations": { "readOnlyHint": true, "destructiveHint": false }, "tags": ["rating", "player"] }, { "name": "record_game_result", "title": "Record Game Result", "description": "Record the result of a chess game and update player ratings", "inputSchema": { "type": "object", "properties": { "white_player_id": { "type": "string", "description": "White player identifier" }, "black_player_id": { "type": "string", "description": "Black player identifier" }, "result": { "type": "string", "enum": ["1-0", "0-1", "1/2-1/2"], "description": "Game result in standard notation" }, "pgn": { "type": "string", "description": "Full game PGN (optional)" }, "time_control": { "type": "string", "description": "Time control (e.g., '10+0', '3+2')" } }, "required": ["white_player_id", "black_player_id", "result"] }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false }, "tags": ["rating", "game"] } ] } ```