Opens in a new tabSkip to content
Agent LighthouseAgent Lighthouse

    Searches the text of every published page. The evidence sources themselves are not in this index — search all of them on the trusted sources page.

    GitHub ↗
    Browse checks and page contents
    agent-interfaces/mcp-tools-list-determinism

    tools/list Determinism and Cache-Hint Compliance

    What it checks

    Repeatedly fetches tools/list, and asserts three things the spec ties directly to agent cost and latency:

    • caching hints are present and well-formed — ttlMs >= 0, cacheScope in {public, private};
    • tool ordering is stable across calls;
    • the tool set does not vary per connection.

    Why it matters

    The spec states its own causal rationale verbatim: deterministic ordering ‘enables clients to reliably cache the tool list and improves LLM prompt cache hit rates when tools are included in model context.’ Tool definitions sit near the front of the model’s prompt. If their serialized bytes change between turns, the provider-side prefix cache misses, and the full tool block is re-billed at uncached rates on every single turn. Separately, servers MUST include caching hints on complete results, and when ttlMs is absent clients SHOULD assume 0 — immediately stale — so an omitted hint converts one cheap cached read into a network round-trip on every access. Both defects are invisible in functional testing and both are measurable with three identical requests.

    Evidence

    • MCP Specification 2026-07-28 — Tools — Model Context Protocol (spec, URL verified 2026-08-20)
    • tools/list result set MUST NOT vary per-connection or as a side effect of other requests (MAY vary by authorization). Servers SHOULD return tools in deterministic order — rationale given verbatim: enables client caching and ‘improves LLM prompt cache hit rates’. inputSchema MUST be a valid JSON Schema object (not null); defaults to JSON Schema 2020-12. Tool names SHOULD be 1-128 chars, case-sensitive, only [A-Za-z0-9_.-], unique within a server. Full x-mcp-header constraint list including static-reachability rule (chain of only properties keys; never through items/oneOf/anyOf/allOf/not/if/then/else/$ref). Clients MUST exclude violating tools from tools/list. If outputSchema present, servers MUST conform. Clients MUST treat annotations as untrusted.
    • MCP Specification 2026-07-28 — Caching — Model Context Protocol (spec, URL verified 2026-08-20)
    • ‘Servers MUST include caching hints on results with resultType: “complete”’ for server/discover, tools/list, prompts/list, resources/list, resources/templates/list, resources/read. ttlMs is an integer ms; servers MUST provide ttlMs >= 0. If ttlMs is absent clients SHOULD assume 0 = immediately stale. cacheScope is exactly “public” or “private”. Servers MUST apply the same cacheScope to all pages of a paginated list. Public scope on an authenticated endpoint may be shared across access tokens — servers MUST NOT rely on cacheScope for access control.

    How it scores

    Tier per evidence policy: scored — grade A meets the A/B bar required for scored audits.

    Example failure

    A Go-based server builds its tools slice by ranging over a map[string]Tool. Go randomizes map iteration order, so tools/list returns the same 24 tools in a different order on every call. Every agent turn that includes the tool block produces a different prefix. The provider’s prompt cache misses 100% of the time. The customer pays full input-token rates on about 18k tokens of tool schema per turn, instead of the cached rate. The same server omits ttlMs entirely, so clients treat the list as immediately stale and refetch it before every turn as well.

    Sources