retoor
251c3dc2ba
- wire spec: lifecycle, stdio + Streamable HTTP transports, tools, utilities, legacy SSE, versioning, changelog (14 Tier 1) - client ecosystem: Claude Code/VS Code/Cursor/Codex configs, mcp-remote, Smithery, registries, Glama (12 Tier 1) - security/ops: authorization draft, trust model, poisoning, rug pulls, production hardening (12 Tier 1) + 68 Tier 2 cards - conclusions: minimal stdlib client on 2025-11-25, normalizer + resolver agent for pasted configs/GitHub URLs, untrusted-until- consent trust model; nothing built yet - audit PASS (14 subjects, 797 sources, 32 conclusions)
57 lines
3.8 KiB
Markdown
57 lines
3.8 KiB
Markdown
# Tools: tools/list + tools/call + error split (2025-11-25)
|
|
|
|
## Metadata
|
|
|
|
| Field | Value |
|
|
|---|---|
|
|
| Institute | Molodetz Institute - Research & Retrieval Division |
|
|
| Subject | mcp-client-support |
|
|
| Document type | Source Dossier |
|
|
| Tier | 1 |
|
|
| Source title | Tools (MCP Specification v2025-11-25) |
|
|
| Source URL | https://modelcontextprotocol.io/specification/2025-11-25/server/tools |
|
|
| Source publisher / author | Model Context Protocol authors (Anthropic-donated open project; site docs) |
|
|
| Source type | standard |
|
|
| Source date (published) | 2025-11-25 (version stamp; no other publish date stated) |
|
|
| Date researched | 2026-10-18 |
|
|
| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
|
|
| Research method | gather-subagent direct page fetch, parent synthesis from evidence pack |
|
|
| Confidence | High |
|
|
| Status | Active |
|
|
|
|
## Summary
|
|
|
|
This page defines the server tools feature: capability declaration with optional `listChanged`, paginated `tools/list`, and `tools/call` with `name`/`arguments` params returning `content` plus `isError`. Its central point for clients is the two-track error model: protocol errors are standard JSON-RPC errors (for example unknown tools), while tool execution failures arrive as successful results with `isError: true`. It also lists content types (text, image, audio, resource_link, embedded resource, optional structuredContent) and client security guidance.
|
|
|
|
## Key findings
|
|
|
|
- "Servers that support tools MUST declare the `tools` capability", with optional `listChanged`.
|
|
- `tools/list` "supports pagination" (`cursor` param, `nextCursor` in result).
|
|
- `tools/call` params: `{"name": …, "arguments": {…}}`; result: `{"content": […], "isError": false}`.
|
|
- "Tools use two error reporting mechanisms: 1. Protocol Errors: Standard JSON-RPC errors… Unknown tools… 2. Tool Execution Errors: Reported in tool results with `isError: true`"; "Clients SHOULD provide tool execution errors to language models."
|
|
- Protocol-error example: `{"code": -32602, "message": "Unknown tool: invalid_tool_name"}`.
|
|
- Unstructured content types: `text`, `image` (base64 plus `mimeType`), `audio`, `resource_link`, embedded `resource`; plus optional `structuredContent` object validated against `outputSchema` when present.
|
|
- Client security guidance: "Implement timeouts for tool calls", "Validate tool results before passing to LLM", "treat tool annotations as untrusted."
|
|
|
|
## Pros / strengths
|
|
|
|
- The JSON-RPC-error vs `isError: true` split is stated normatively with examples, which is exactly the distinction a client must get right to avoid misrouting tool failures as transport faults.
|
|
- Request and result shapes are given literally (`name`/`arguments`, `content`/`isError`, `cursor`/`nextCursor`), so the data plane is implementable without inference.
|
|
- Security guidance is client-actionable (timeouts, result validation, untrusted annotations) rather than vague.
|
|
|
|
## Cons / limitations / caveats
|
|
|
|
- No explicit author names or publish dates appear on the page; the date above is the version stamp in the URL, per the pack's Uncertainty notes.
|
|
- Content-type breadth (image, audio, resource_link, embedded resource, structuredContent with outputSchema validation) means a minimal client must decide up front how much result rendering to support versus passing through.
|
|
- `listChanged` notification handling and `outputSchema` validation are extra client work beyond the two-method core, not covered in depth here.
|
|
|
|
## Relevance to tai
|
|
|
|
This is the entire tools data plane for a minimal client: two methods, a pagination loop, and the critical JSON-RPC-error vs `isError: true` distinction. Combined with the lifecycle handshake, this page plus transports is nearly the whole minimal-client spec.
|
|
|
|
## Changelog
|
|
|
|
| Date | Change |
|
|
|---|---|
|
|
| 2026-10-18 | Initial dossier created. |
|