# 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. Last verified against MCP specification 2026-07-28: Key changes on 2026-11-18.

## 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 `ttlMs` and `cacheScope` fields on results returned by `tools/list`, `prompts/list`, `resources/list`, `resources/read`, and `resources/templates/list` via a new `CacheableResult` interface.

Source: [MCP specification 2026-07-28: Key changes](https://modelcontextprotocol.io/specification/2026-07-28/changelog)

## How to fix it

Add "ttlMs": 300000 and "cacheScope": "private" (use "public" only if the list is the same for every user).

1. TypeScript: pass cacheHints: { "tools/list": { ttlMs, cacheScope } } in the McpServer options.
2. Python: pass cache_hints={"tools/list": CacheHint(ttl_ms=..., scope=...)} to MCPServer.
3. Use "private" unless every user sees the same list; a few minutes is a sensible ttlMs.

### TypeScript SDK

```ts
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

```python
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"
```

## 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](https://isokron.ai/mcp-check/checks/spec-envelope-result-type)
- [The paste holds the whole tool list](https://isokron.ai/mcp-check/checks/spec-pagination-partial)
- [x-mcp-header values follow the rules](https://isokron.ai/mcp-check/checks/spec-x-mcp-header)
- [MCP specification 2026-07-28: tools/list rules](https://isokron.ai/mcp-check/checks/protocol)

## Further reading

- [Shipping a production MCP server on the 2026-07-28 spec](https://isokron.ai/research/production-mcp-server)

Counts toward: MCP specification 2026-07-28.

Rubric: https://isokron.ai/mcp-check/rubric

Check your tool list: https://isokron.ai/mcp-check
