Skip to main content
skill CX Codex

tool-budget-audit — Claude Code skill: context audit

tool-budget-audit is a Claude Code skill that measures context used by tool schemas and call results. It flags catalog bloat and mistaken tool choices.

MIT ★ 741 updated 2026-11-11

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add MiniMax-AI/mcode-stack
/plugin install ronny@mcode-stack
Open on GitHub

What tool-budget-audit does

tool-budget-audit measures how much context an agent spends on tool definitions, returned data, and extra model requests. It asks for tokenizer-based estimates and observations from real tasks, then identifies the main bottleneck.

The workflow starts by merging overlapping tools, clarifying names and return formats, and grouping tools by domain. Low-frequency tools can move to tool search, while filtering, aggregation, and parallel batches can move into programmatic calls. The output is a short report with measured figures, concrete tool names, and the next measurement to run. The companion checklist is checklists/tool-budget.md.

The audit also covers catalog fetches over the network, descriptions that reduce search recall, and name-based reminders or counters that stop firing after a tool moves into a program. End-to-end comparison uses harness-experiment.

What it helps with

  • measure tokens spent on tool definitions
  • compare returned data with model request count
  • find tools that look similar to the agent
  • decide which tools to merge or group
  • choose between tool search and programmatic calls

Example prompts for the agent

  • Audit every tool and MCP server in this project for context usage.
  • Measure definitions, call counts, request counts, and result sizes on two representative tasks.
  • Write the short report with the bottleneck, named tools, and the next measurement.

How to install tool-budget-audit

1Plugin marketplace

/plugin marketplace add MiniMax-AI/mcode-stack
/plugin install ronny@mcode-stack

This installs the whole ronny plugin with all its skills

2Skills CLI (Vercel)

npx skills add MiniMax-AI/mcode-stack --skill tool-budget-audit -a claude-code

3Manually: put the files in place

~/.claude/skills/tool-budget-audit/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/tool-budget-audit/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about tool-budget-audit

How do I install tool-budget-audit in Claude Code?

Add the marketplace with /plugin marketplace add MiniMax-AI/mcode-stack, then install the skill with /plugin install ronny@mcode-stack.

What does tool-budget-audit do?

It measures context spent on tool schemas, call results, and model round trips. It then guides the choice between reducing the catalog, adding tool search, and using programmatic calls.

How does tool-budget-audit validate its recommendation?

It compares score, request count, and token usage before and after each change. The end-to-end experiment uses harness-experiment.

Source text

SKILL.md · MIT
---
name: tool-budget-audit
description: Audit how much context an agent's tools consume, through tool definitions and tool results, and decide whether to trim the catalog, add tool search, or add programmatic tool calling. Use when an agent has many tools or MCP servers, picks the wrong tools, or burns context on tool output.
---

# Tool Budget Audit

Tools cost context in two ways, plus one side effect:

- **Definitions.** Every tool's name, description and parameter schema sits
  in context whether or not it is used this turn.
- **Intermediate results.** Every call puts its full output back into the
  conversation, and every round trip is another full model request.
- **Side effect: wrong picks.** Similar names and vague descriptions make the
  model choose the wrong tool or pass wrong arguments.

Tool search mainly saves the first cost. Programmatic tool calling (the model
writes a small program that calls tools) mainly saves the second.

Companion to MCode Engineering Notes 02, "Too many tools will eat your
context". Plain-text checklist: `checklists/tool-budget.md`.

## 1. Measure first

Work from the target project's code and real requests, not from guesses:

1. List every tool exposed to the model, grouped by source (built-in, each MCP
   server, plugins).
2. Estimate the token size of each tool definition with a tokenizer and sum it.
   Say which tokenizer you used; it is a relative measure.
3. For one or two representative tasks, record how many tool calls were made,
   how many model requests that caused, and how large the tool results were.
4. Note which tools are used almost every turn and which are rarely used.

Report the numbers you measured. If you cannot measure something, say so
instead of estimating.

## 2. Step 0 - subtract

- **Merge by user intent.** Do not map APIs one to one. "List issues",
  "filter issues by label" and "filter by author" can be one tool with
  parameters.
- **Make names and descriptions distinguishable.** Two tools whose
  descriptions read alike will be confused. State the return format.
- **Group.** Put tools into namespaces by domain, keeping each group small.
- **Decide what stays resident.** Read, edit, search and run-command style
  tools used nearly every turn should always be loaded.

## 3. Step 1 - deferred loading and tool search

Consider it when there are many tools and most are rarely used.

- Keep core high-frequency tools resident; make low-frequency tools
  searchable.
- If a search miss means a tool "does not exist", check descriptions again:
  vague descriptions break recall.
- Test tool search recall on **your own** tool set. Results on clean
  benchmarks do not transfer to messy real catalogs.
- Tools whose catalog must be fetched over the network every turn can slow
  the first token. Consider keeping them resident instead.
- When debugging, check what the model had actually seen at that moment, not
  just what the request listed.

## 4. Step 2 - programmatic tool calling

Consider it when there is a lot of data to filter or aggregate, three or more
dependent calls, or batch operations that could run in parallel.

- Actually move tools into the program. Offering a code tool next to all the
  normal tools tends to go unused.
- Keep at top level: tools that interact with the user, change session state,
  need their result read before deciding the next step (tool search, loading
  a skill), browser and publishing tools, and spawning subagents.
- Calls from inside the program must go through the same validation, hooks,
  permission prompts and UI as direct calls.
- Tool failures should return an error result, not throw, so one failure does
  not discard the whole program.
- Prefer structured tool output so the program can pick the fields it needs.
  A program that returns raw output saves nothing.
- Search the codebase for logic keyed on tool names (reminders, counters,
  analytics). It silently stops firing once a tool moves into the program.

## 5. Decide

| Bottleneck | First move |
| --- | --- |
| Too many or too similar tools | Subtract, merge, rename, group |
| Definitions take too much context | Tool search |
| Results take too much context, too many round trips | Programmatic tool calling |
| Arguments often wrong | Better descriptions and examples |

The steps stack. A clean catalog makes tool search work; working tool search
makes programmatic calling work. Run an end-to-end eval before and after each
step and look at score, request count and tokens together
(see `harness-experiment`).

## Output

A short report: measured numbers, the main bottleneck, the recommended next
step with concrete tool names, and what to measure afterwards.

© Ronny (MiniMax Code team) · MIT · MiniMax-AI/mcode-stack

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set27

The whole set →
subagent-split-check subagent-split-check is a Claude Code skill that decides whether work belongs in a subagent or the main loop. It checks context boundaries before a split. CX Codex +1 ★ 741repo stars context-tax-audit The context-tax-audit skill for Claude Code inventories injected data in agent requests to reduce token usage. It identifies redundant prompt blocks and configurations that hinder prompt cache performance. CX Codex +1 ★ 741repo stars long-session-check long-session-check is a Claude Code skill that audits long-session context and memory handling. It starts when constraints get lost or compaction has happened several times. CX Codex +1 ★ 741repo stars long-command-check long-command-check is a Claude Code skill that audits shell command execution in agent harnesses. It checks dev server hangs, timeouts, backgrounding, and prompt cache expiration. CX Codex +1 ★ 741repo stars pr-quiz pr-quiz is a Claude Code skill that drafts multiple-choice questions for PR authors. It triggers when the MCode Review pipeline requests an author quiz. CX Codex +1 ★ 741repo stars pr-review pr-review is a Claude Code skill that reviews pull requests and branches with MCode Review rules. It runs from CI or on a developer’s request before human review. CX Codex +1 ★ 741repo stars pr-review-tuning pr-review-tuning is a Claude Code skill that automates the weekly tuning loop for a code review bot. It evaluates recent pull requests and proposes rule updates based on performance metrics. CX Codex +1 ★ 741repo stars lifting-loops lifting-loops is a Claude Code skill that finds repeated manual steps in agent work and suggests rules, scripts, or scheduled tasks. Run it for a retro, with /lifting-loops, or on the weekly schedule. CX Codex +1 ★ 741repo stars

Project sponsors

Companies that keep this analytics open