MCP Token Counter: Why Your Tools Are Silently Eating Your Context Window

You connected an MCP server. Your agent is working. Everything looks fine. But somewhere in the background, your AI budget is draining faster than it should — and the culprit isn't your conversation history or your documents. It's the tools themselves.

This is one of the most overlooked costs in MCP-based AI systems, and it compounds silently as you add more tools to your server.

How MCP Tool Definitions Consume Tokens

When an AI model supports tool use, it needs to understand what tools are available before it can decide which one to call. This understanding comes from a schema — a structured description of each tool's name, purpose, and parameters.

In the MCP protocol, this schema is delivered automatically. When your client calls tools/list at session start, the server returns a JSON array of every tool it exposes. The MCP client then forwards these definitions to the language model as part of the request payload — on every single message in the conversation.

Here is what a single tool definition looks like when serialized:

{
  "name": "search_repositories",
  "description": "Search GitHub repositories by keyword, language, or topic.
    Returns repository name, description, star count, primary language,
    last updated date, and clone URL. Supports pagination with page and
    per_page parameters. Use sort to order by stars, forks, or
    recently updated.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search query with GitHub search syntax support"
      },
      "language": {
        "type": "string",
        "description": "Filter by programming language"
      },
      "sort": {
        "type": "string",
        "enum": ["stars", "forks", "updated"],
        "description": "Sort order for results"
      },
      "page": { "type": "number", "description": "Page number (default: 1)" },
      "per_page": { "type": "number", "description": "Results per page, max 100" }
    },
    "required": ["query"]
  }
}

That single tool definition is approximately 280–320 tokens. Now multiply by 40 tools in a typical GitHub MCP server and you have around 12,000 tokens of overhead — before a single word of your actual prompt is processed.

Why This Matters

The Context Window Math

Let's break down where a typical 128,000-token context window actually goes in an MCP-powered agent:

The key insight: tool definitions are a fixed cost per request. Unlike conversation history which accumulates, tool overhead doesn't grow — but it also never goes away. Optimizing it is a one-time investment with permanent returns.

Measuring Your MCP Server's Token Footprint

Before you can optimize, you need to know where you stand. The MCP Token Counter at MCP Playground does this in seconds — no sign-up, no installation.

How to use it:

The color coding gives you instant signal:

• Green (under 4,000 tokens) — healthy, your tool footprint is well-managed
• Amber (4,000–10,000 tokens) — worth reviewing; trimming could meaningfully reduce spend
• Red (10,000+ tokens) — high overhead; optimization is strongly recommended

5 Strategies to Reduce MCP Token Overhead

Strategy 1 — Trim Verbose Tool Descriptions

Tool descriptions are the biggest variable in token cost. Developers often write them as full paragraphs of documentation, but models only need enough to make a routing decision. Compare these two descriptions for the same tool:

"description": "Searches the repository
for files matching a given glob pattern.
This tool is useful when you need to find
files by their name or extension across
the entire repository tree. It supports
standard glob wildcards including * and **
for recursive matching. Returns a list of
matching file paths relative to the
repository root."

"description": "Find files by glob
pattern. Returns matching paths."

That's a 75% reduction for a single description. Across 40 tools, trimming descriptions from 80 tokens to 20 tokens saves approximately 2,400 tokens per request.

Strategy 2 — Trim Parameter Descriptions

Parameter descriptions are often as bloated as tool descriptions — and they multiply by the number of parameters per tool. If a parameter is named user_id with type string, the description "The unique identifier of the user whose data you want to retrieve" adds tokens without adding clarity.

For parameters with obvious names, the description can be as short as the type and a one-clause constraint:

// Before: ~25 tokens
"description": "The unique identifier of the repository in owner/name format"

// After: ~10 tokens
"description": "Repository in owner/name format"

Strategy 3 — Split into Focused Servers

Instead of one server with 60 tools covering every operation your platform supports, build smaller purpose-specific servers:

An agent that only needs to read from GitHub connects to the read server alone — and pays for 8 tools instead of 40. For agents that need everything, you can connect multiple servers but you now have visibility into the exact cost of each capability layer.

Strategy 4 — Filter Tools per Agent at Runtime

Some MCP server implementations support tool filtering — you can pass a list of tool names to allow or deny at session initialization. If your framework supports it, pass only the tools relevant to the current task:

// Claude Desktop config — restrict to specific tools
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "..." },
      "allowedTools": ["list_issues", "create_issue", "add_comment"]
    }
  }
}

This is particularly effective for specialized agents: a "triage bot" that only creates and comments on issues doesn't need the 35 other GitHub tools in its context.

Strategy 5 — Remove or Stub Rarely Used Tools

The token counter's per-tool ranking makes this obvious: sort by token cost, then look at the top 20%. These are usually tools with the longest descriptions and most complex schemas. For each one, ask: how often does the AI actually call this?

If a tool is called less than 1% of the time but costs 500+ tokens per request, it's a candidate for removal or stubbing (replacing with a minimal no-op that can be re-enabled for specific sessions).

Tradeoffs to Keep in Mind

The right optimization strategy depends on your traffic patterns. For low-volume, long-context workloads (deep research agents, document analysis), token overhead from tools is negligible and description richness is more important. For high-volume, short-context workloads (customer support bots, automated triage), every token counts.

Quick Reference: Token Cost Benchmarks

Based on analysis of popular public MCP servers:

The Workflow: Measure, Identify, Optimize, Re-measure

Treating token overhead as a first-class concern follows the same pattern as any performance optimization:

Further Reading

• MCP Specification — Tools
• OpenAI — Function Calling Token Usage
• Anthropic — Prompt Caching
• What Is the Model Context Protocol? — MCP Playground
• MCP Automation Workflows: 5 Developer Recipes for 2026
• MCP Security Scanner — Free tool to audit your server