MCP specification 2026-07-28: tools/list rules
Revision 2026-07-28 adds resultType, ttlMs and cacheScope to every tools/list result, defines x-mcp-header for mirroring arguments into HTTP headers, and keeps the rules for tool fields, _meta keys, icons and pagination.
These checks cover the parts of the 2026-07-28 specification a tool list can break on its own, beyond names and schemas. Some failures are silent: a conforming HTTP client drops a tool with an invalid x-mcp-header without telling anyone.
Current SDKs fill in the envelope fields for you; most findings here come from hand-written servers, proxies and older SDK versions.
The 12 checks
- Every list entry is a tool object with a name: Each entry of the tools array in a tools/list result is a tool object identified by a string name, with an inputSchema; an entry that is not an object or has no name cannot be called.
- x-mcp-header values follow the rules: x-mcp-header (MCP 2026-07-28) mirrors an argument into an HTTP header; its value must be a non-empty RFC 9110 token, unique ignoring case, on a string, integer or boolean property directly under "properties", or HTTP clients drop the tool.
- No x-mcp-header on secrets or personal data: Do not put x-mcp-header on passwords, API keys, tokens or personal data: header values are visible to, and often logged by, every network intermediary; mirror only routing values such as region or tenant.
- Tool fields have the types the schema defines: Tool fields must have the types schema.ts defines: name, title and description are strings, each annotation hint is a boolean, outputSchema and _meta are objects, icons is an array; "readOnlyHint": "true" is a string, not true.
- Icon sources are https: or data: URIs: Tool icon sources should be https: or data: URIs; clients MUST reject unsafe schemes such as javascript:, file:, ftp: and ws:, so the tool shows without its icon.
- _meta keys follow the key-name grammar: A _meta key is an optional prefix of dot-separated labels ending in a slash, then a name that begins and ends with a letter or digit, for example com.example/feature-flag; keys outside that grammar may be ignored or rejected.
- _meta keys avoid prefixes reserved for MCP: Any _meta prefix whose second label is mcp or modelcontextprotocol is reserved for the specification and official extensions; a server should use its own reverse-DNS prefix such as com.example/.
- The tools/list result carries resultType: Revision 2026-07-28 requires every result to carry resultType, which is "complete" for tools/list; clients treat a missing value as "complete" from an older server, but a 2026-07-28 server must send it.
- The tools/list result carries ttlMs and cacheScope: Since 2026-07-28, tools/list results carry ttlMs (how long, in milliseconds, a client may cache the list, at least 0) and cacheScope ("public" or "private"); set them through the SDK’s cache hints.
- The paste holds the whole tool list: When a tools/list answer carries nextCursor it is only one page; call tools/list again with that cursor until none comes back, and check all pages together.
- No tool-level execution field from 2025-11-25: Revision 2026-07-28 moved experimental tasks out of the core protocol into the io.modelcontextprotocol/tasks extension, so clients on the new revision ignore a tool’s 2025-11-25 "execution" field.
- Annotation hints use the spec’s key names: ToolAnnotations keys are camelCase (readOnlyHint, destructiveHint, idempotentHint, openWorldHint); a snake_case key such as destructive_hint is not a hint, so clients ignore it and apply the default instead.
Other topics
- MCP tool annotations
- Directory review rules for MCP tools
- MCP tool names
- MCP tool descriptions
- MCP tool input and output schemas
- Tool poisoning and hidden text
- Write-surface design for MCP tools
Sources last verified on 2026-11-18. How findings become grades.
Check your tool list: paste your tools/list, nothing is sent anywhere