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.
Check spec-envelope-cache · MCP specification 2026-07-28 · default severity: attention (or blocking, advice, depending on the case) · rubric 2.1.0
What fails
ttlMs (a number of at least 0) says how long a client may cache the list; cacheScope ("public" or "private") says whether shared caches may reuse it. A missing pair is a gap for a 2026-07-28 server; a wrong value is an error for any server that sends it.
The rule
Require
ttlMsandcacheScopefields on results returned bytools/list,prompts/list,resources/list,resources/read, andresources/templates/listvia a newCacheableResultinterface.
How to fix it
Add "ttlMs": 300000 and "cacheScope": "private" (use "public" only if the list is the same for every user).
- TypeScript: pass cacheHints: { "tools/list": { ttlMs, cacheScope } } in the McpServer options.
- Python: pass cache_hints={"tools/list": CacheHint(ttl_ms=..., scope=...)} to MCPServer.
- Use "private" unless every user sees the same list; a few minutes is a sensible ttlMs.
TypeScript SDK
import { McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod';
const server = new McpServer({ name: 'issues', version: '1.0.0' }, { cacheHints: { 'tools/list': { ttlMs: 300000, cacheScope: 'private' } } });
server.registerTool(
'get_issue',
{
title: 'Get issue',
description: 'Return one issue by ID. Use when the user names an issue.',
inputSchema: z.strictObject({
issue_id: z.string().describe('Issue ID, for example ISS-42'),
}),
annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
},
async ({ issue_id }) => ({ content: [{ type: 'text', text: 'Done' }] }),
);Python SDK
from typing import Annotated
from pydantic import Field
from mcp.server.mcpserver import MCPServer
from mcp.types import ToolAnnotations
from mcp.server.caching import CacheHint
server = MCPServer("issues", cache_hints={"tools/list": CacheHint(ttl_ms=300_000, scope="private")})
@server.tool(
title="Get issue",
annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False, openWorldHint=False),
)
def get_issue(
issue_id: Annotated[str, Field(description="Issue ID, for example ISS-42")],
) -> str:
"""Return one issue by ID. Use when the user names an issue."""
return "Done"Run against @modelcontextprotocol/server 2.4.0, mcp 2.3.0 and fastmcp 4.2.2 on 2026-11-18; the checker confirms this check passes on the tool list each snippet produces.
Questions
What happens with ttlMs: 0?
The list is stale immediately, so clients may ask for it again before each use. It is valid; it just saves nothing.
When is cacheScope "public" safe?
Only when the list is identical for every user and authorization context. If tools depend on the user’s permissions, use "private".
Related checks
- The tools/list result carries resultType
- The paste holds the whole tool list
- x-mcp-header values follow the rules
- All checks in MCP specification 2026-07-28: tools/list rules
Further reading
How this check is graded
It counts toward: MCP specification 2026-07-28. See the rubric.
Last verified against MCP specification 2026-07-28: Key changes on 2026-11-18. The rule above is quoted in the source’s own words. This page as Markdown.
Check your tool list: paste your tools/list, nothing is sent anywhere