Agent Wranglers

AGT-17Recommended

Send cache hints and a stable order with every list

Return list results in the same order while the set is unchanged. Give each cacheable result a ttlMs, and a cacheScope of private whenever it depends on who asks.

By Agent Wranglers. Updated .

How to do it

The 2026-07-28 revision requires ttlMs and cacheScope on tools/list, prompts/list, resources/list, resources/templates/list and resources/read. A stable order lets clients cache the list and keeps the model provider's prompt cache warm. Sort by name rather than by registration order or a hash map. Use public only for answers that are the same for every caller. A tool list filtered by scope is private, or a shared proxy hands one user's tools to another. Set ttlMs from how often the list changes, such as 300,000 for a list that changes with deploys. Send notifications/tools/list_changed on subscriptions/listen when it changes sooner. The same idea for HTTP is Keep private pages out of shared caches.

Examples

JavaScript example

const LIST_TTL_MS = 300_000;
export const toolListResult = (tools, variesByCaller) => ({
  resultType: 'complete',
  tools: [...tools].sort((a, b) => a.name.localeCompare(b.name)),
  ttlMs: LIST_TTL_MS,
  cacheScope: variesByCaller ? 'private' : 'public',
});

Python example

LIST_TTL_MS = 300_000

def tool_list_result(tools: list[dict], varies_by_caller: bool) -> dict:
    return {"resultType": "complete", "tools": sorted(tools, key=lambda tool: tool["name"]),
            "ttlMs": LIST_TTL_MS, "cacheScope": "private" if varies_by_caller else "public"}

How to check

Call tools/list twice with the same token. The two answers are identical byte for byte, and both carry ttlMs and cacheScope. A list that changes with the token's scopes says "cacheScope": "private".

Sources

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/agents-as-users/mcp-servers/list-cache-hints">Agent Wranglers agents as users playbook</a>. In code you write, add a comment next to it with the same link.