MCP tools/list order and prompt caching: keying a Sume cache

Sume's tools/list returns a single array, built by filtering a fixed registry, so the tools come back in registry order. It has no pagination cursor. The list differs by credential and scope, so cache it per credential and refetch when the token, its scopes, or the server deployment changes.

Read from the hosted MCP server source and MCP tools and gates on 2026-10-01. I did not rely on any outside spec text for this post.

What does tools/list return?

The handler returns { tools: [...] }, a plain array with no cursor field. Each call recomputes the visible tools from the registry for the calling credential. Filtering keeps the registry's relative order, so two sessions with the same credential, scope and server build see the same sequence.

What changes the list?

Not every client sees the same tools. These are the factors visible in the source and docs.

How should I key a tool-list cache?

Use the credential identity, its granted scopes, and the server host as the key. Store the array exactly as received, in order, because a prompt prefix built from it is only reusable if the bytes match. Refetch after re-authorizing with new scopes, after a reconnect, or when a call fails with an unknown-tool result. See tools/list on reconnect in Claude Code.

When should I use tools_list instead?

The docs point to tools_list for the session-visible subset, with safety metadata, and to tools_schema for one contract. For very large catalogs, progressive discovery keeps the always-sent list small, which also keeps the cached prefix short.