Tools changedspecification/2026-07-28/server/tools
Nearest release: v2.1.305, published under an hour before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 20 Oct 2026 20:02 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 20 Oct 2026 20:07 UTC.
Upstream edited
Recorded here
Lines+56added
Lines−58removed
From line
1
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits2to this page, all time
The whole hunk
from line 1, old and new numbered
/
from line 1
11# Tools
22
3<div id="enable-section-numbers" />
4
53The Model Context Protocol (MCP) allows servers to expose tools that can be invoked by
64language models. Tools enable models to interact with external systems, such as querying
75databases, calling APIs, or performing computations. Each tool is uniquely identified by
86a name and includes metadata describing its schema.
97
10<Note>
11 For brevity, the request examples on this page omit the `_meta` request
12 metadata (`io.modelcontextprotocol/protocolVersion`,
13 `io.modelcontextprotocol/clientInfo`, and
14 `io.modelcontextprotocol/clientCapabilities`). Every request **MUST** include
15 the required `_meta` fields; see
16 [`_meta`](/specification/2026-07-28/basic/index#meta).
17</Note>
8> [!NOTE]
9>
10> For brevity, the request examples on this page omit the `_meta` request
11> metadata (`io.modelcontextprotocol/protocolVersion`,
12> `io.modelcontextprotocol/clientInfo`, and
13> `io.modelcontextprotocol/clientCapabilities`). Every request **MUST** include
14> the required `_meta` fields; see
15> [`_meta`](/specification/2026-07-28/basic/index#meta).
1816
1917## User Interaction Model
2018
from line 24
2624suits their needs—the protocol itself does not mandate any specific user
2725interaction model.
2826
29<Warning>
30 For trust & safety and security, there **SHOULD** always
31 be a human in the loop with the ability to deny tool invocations.
27> [!WARNING]
28>
29> For trust & safety and security, there **SHOULD** always
30> be a human in the loop with the ability to deny tool invocations.
31>
32> Applications **SHOULD**:
33>
34> * Provide UI that makes clear which tools are being exposed to the AI model
35> * Insert clear visual indicators when tools are invoked
36> * Present confirmation prompts to the user for operations, to ensure a human is in the
37> loop
3238
33 Applications **SHOULD**:
34
35 * Provide UI that makes clear which tools are being exposed to the AI model
36 * Insert clear visual indicators when tools are invoked
37 * Present confirmation prompts to the user for operations, to ensure a human is in the
38 loop
39</Warning>
40
4139## Capabilities
4240
4341Servers that support tools **MUST** declare the `tools` capability:
from line 295
297295 * Defaults to 2020-12 if no `$schema` field is present
298296* `annotations`: Optional properties describing tool behavior
299297
300<Warning>
301 For trust & safety and security, clients **MUST** consider tool annotations to
302 be untrusted unless they come from trusted servers.
303</Warning>
298> [!WARNING]
299>
300> For trust & safety and security, clients **MUST** consider tool annotations to
301> be untrusted unless they come from trusted servers.
304302
305303#### Tool Names
306304
from line 313
315313 * `DATA_EXPORT_v2`
316314 * `admin.tools.list`
317315
318<Note>
319 Tool name uniqueness is scoped to a single server. Clients or proxies that
320 aggregate tools from multiple servers **MAY** encounter naming collisions (for
321 example, two servers each exposing a `search` tool) and **SHOULD** implement a
322 disambiguation strategy such as prefixing tool names with a server identifier.
316> [!NOTE]
317>
318> Tool name uniqueness is scoped to a single server. Clients or proxies that
319> aggregate tools from multiple servers **MAY** encounter naming collisions (for
320> example, two servers each exposing a `search` tool) and **SHOULD** implement a
321> disambiguation strategy such as prefixing tool names with a server identifier.
322>
323> The server `name` (from `serverInfo`) is not guaranteed to be unique across
324> servers and **SHOULD NOT** be relied upon for disambiguation.
323325
324 The server `name` (from `serverInfo`) is not guaranteed to be unique across
325 servers and **SHOULD NOT** be relied upon for disambiguation.
326</Note>
327
328326#### x-mcp-header
329327
330328The `x-mcp-header` extension property allows servers to designate specific tool
from line 386
388386In this example, when the tool is called with `"region": "us-west1"`, the client adds
389387the header `Mcp-Param-Region: us-west1` to the HTTP request.
390388
391<Warning>
392 Server developers **SHOULD NOT** mark sensitive parameters (passwords, API keys, tokens,
393 PII) with `x-mcp-header`, as header values are visible to network intermediaries.
394</Warning>
389> [!WARNING]
390>
391> Server developers **SHOULD NOT** mark sensitive parameters (passwords, API keys, tokens,
392> PII) with `x-mcp-header`, as header values are visible to network intermediaries.
395393
396394### Tool Result
397395
from line 397
399397
400398**Unstructured** content is returned in the `content` field of a result, and can contain multiple content items of different types:
401399
402<Note>
403 All content types (text, image, audio, resource links, and embedded resources)
404 support optional
405 [annotations](/specification/2026-07-28/server/resources#annotations) that
406 provide metadata about audience, priority, and modification times. This is the
407 same annotation format used by resources and prompts.
408</Note>
400> [!NOTE]
401>
402> All content types (text, image, audio, resource links, and embedded resources)
403> support optional
404> [annotations](/specification/2026-07-28/server/resources#annotations) that
405> provide metadata about audience, priority, and modification times. This is the
406> same annotation format used by resources and prompts.
409407
410408#### Text Content
411409
from line 455
457455
458456Resource links support the same [Resource annotations](/specification/2026-07-28/server/resources#annotations) as regular resources to help clients understand how to use them.
459457
460<Info>
461 Resource links returned by tools are not guaranteed to appear in the results
462 of a `resources/list` request.
463</Info>
458> [!NOTE]
459>
460> Resource links returned by tools are not guaranteed to appear in the results
461> of a `resources/list` request.
464462
465463#### Embedded Resources
466464
from line 489
491489
492490For backwards compatibility, a tool that returns structured content SHOULD also return the serialized JSON in a TextContent block.
493491
494<Note>
495 `structuredContent` is server-produced result data and is unrelated to LLM
496 "structured outputs" (schema-constrained model generation).
497</Note>
492> [!NOTE]
493>
494> `structuredContent` is server-produced result data and is unrelated to LLM
495> "structured outputs" (schema-constrained model generation).
498496
499497#### Output Schema
500498
from line 670
672670
673671## Stateful Tools
674672
675<Note>
676 This section is non-normative guidance for tool design. The protocol has no
677 concept of a state handle; from the wire's perspective a handle is an ordinary
678 string in a tool result and an ordinary argument to subsequent tool calls.
679</Note>
673> [!NOTE]
674>
675> This section is non-normative guidance for tool design. The protocol has no
676> concept of a state handle; from the wire's perspective a handle is an ordinary
677> string in a tool result and an ordinary argument to subsequent tool calls.
680678
681679MCP has no protocol-level session, so a server cannot rely on implicit
682680per-connection state to relate one tool call to the next. Servers that need to
No line in this hunk matches that.