---
title: "Keep the tool list within a token budget · Agent Wranglers"
url: https://agentwranglers.se/playbook/agents-as-users/mcp-servers/tool-list-budget
id: AGT-15
level: Recommended
updated: 2026-10-22
tokens: 1028
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Keep the tool list within a token budget

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [MCP servers](https://agentwranglers.se/playbook/agents-as-users/mcp-servers.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-22.

- ID: AGT-15
- Level: Recommended
- Chapter: [MCP servers](https://agentwranglers.se/playbook/agents-as-users/mcp-servers.md)
- Rule: Set a token budget for the whole `tools/list` answer and fail the build when it grows past it. Each tool's description says when to use it and when not to.
- Check: A test calls `tools/list` with a token that holds every scope and counts the tokens of the JSON answer with a common tokenizer. The count is under the budget written in the repository. Every description has a "Use when" or "Do not use" sentence.
- How: Clients put every tool definition into the model's context on every turn. A 40-tool server with long descriptions costs each user thousands of tokens before any work starts. Pick a budget, such as 8,000 tokens, and write it in the repository. Merge tools that differ only by a filter into one tool with an enum argument. Move long reference text into a resource the tool links to. Return only the tools the caller's scopes allow, which the specification permits. Name and shape each tool as [Design tools like a small public API](https://agentwranglers.se/playbook/ai-features/structured-output-and-tools/tool-design.md) says. Measure the effect of each change with [Keep a set of tasks with the tools they need](https://agentwranglers.se/playbook/agents-as-users/tool-choice-evals/tool-choice-cases.md).

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### JavaScript example

```js
import { encode } from 'gpt-tokenizer';
const TOOL_LIST_TOKEN_BUDGET = 8000;

test('tool list fits its budget', async () => {
  const { tools } = await client.listTools();
  expect(encode(JSON.stringify(tools)).length).toBeLessThan(TOOL_LIST_TOKEN_BUDGET);
  tools.forEach(tool => expect(tool.description).toMatch(/Use when|Do not use/));
});
```

### Python example

```python
import json
import tiktoken

TOOL_LIST_TOKEN_BUDGET = 8000

def test_tool_list_fits_its_budget(client):
    tools = client.list_tools()["tools"]
    tokens = len(tiktoken.get_encoding("o200k_base").encode(json.dumps(tools)))
    assert tokens < TOOL_LIST_TOKEN_BUDGET
    assert all("Use when" in tool["description"] or "Do not use" in tool["description"] for tool in tools)
```

## Sources

- [MCP specification on tools](https://modelcontextprotocol.io/specification/2026-07-28/server/tools)

## Related rules

- AIF-15 [Design tools like a small public API](https://agentwranglers.se/playbook/ai-features/structured-output-and-tools/tool-design.md) in AI features
- AGT-28 [Keep a set of tasks with the tools they need](https://agentwranglers.se/playbook/agents-as-users/tool-choice-evals/tool-choice-cases.md) in Agents as users
- AGT-31 [Rerun the tool evals on every tool change](https://agentwranglers.se/playbook/agents-as-users/tool-choice-evals/evals-on-tool-change.md) in Agents as users

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/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/tool-list-budget">Agent Wranglers agents as users playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Reject MCP requests whose headers disagree with the body](https://agentwranglers.se/playbook/agents-as-users/mcp-servers/mcp-header-validation.md)
- Next: [Report bad arguments as tool results instead of protocol errors](https://agentwranglers.se/playbook/agents-as-users/mcp-servers/tool-errors-as-results.md)
- [MCP servers](https://agentwranglers.se/playbook/agents-as-users/mcp-servers.md)