toolism CLI
toolism measures tokens spent on tool and MCP definitions and trims them without changing which calls are valid.
- 54 ★ on the repository
- Last commit
- MIT
Minimal access
Why this level
- It reads tool schemas and, when reading from an MCP server, launches it on your machine.
- It changes only the schema files you point it at.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/toolismDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewMinimal accessThe tool runs nothing and makes no network calls.
- It reads tool schemas and, when reading from an MCP server, launches it on your machine.
- It changes only the schema files you point it at.
This is third-party code. Review the repository files before installing.
What it does
toolism is a Python CLI and library for the tool schemas an agent receives with every request: OpenAI functions, Anthropic tools and MCP server tools. Schema generators such as Pydantic, FastMCP and zod-to-json-schema add what the model already knows: repeated titles, `anyOf` wrappers, `default: null`, `$schema` URIs and unused `$defs`. toolism removes only that padding. On the author's benchmark of 14 sets and 159 tools from 13 popular MCP servers, default rules cut definitions by 37.4% in total, with a median of 11.3% per set and up to 73% on Notion. The `--verify` option checks that a changed schema accepts the same calls. `toolism check` works as a CI gate, and a GitHub Action and a pre-commit hook exist.
Who it is for. Authors of MCP servers and agents who pay for tool definitions in every request and want to cut that cost without breaking calls.
Good fit when
- You want to know how many tokens the tools of your MCP server take.
- Pydantic schemas are bloated and should be compressed with an equivalence proof.
- CI needs a gate that stops definition cost from creeping up.
- An MCP configuration in `~/.cursor/mcp.json` must be compared by token spend.
Not a fit when
- Schemas are already hand-tuned and compact: the gain is almost zero.
- System prompts need trimming rather than tool schemas.
- Changing the set of valid tool calls for size is acceptable.
Example request
Measure how many tokens my MCP server's tools take and show which rules would cut the definitions without breaking calls.Limitations
The gain depends on the schema generator and is near zero for carefully hand-written schemas. `--verify` needs the `toolism[verify]` extra and checks call acceptance by tests in some cases rather than by proof. Anthropic's exact token counter is in the `toolism[all]` set. To read tools straight from an MCP server you need the `toolism[mcp]` extra, and the server is launched on your machine.
How to disable. Remove the package with `pip uninstall toolism` or `pipx uninstall toolism`. Delete the `.toolism/baseline.json` baseline file and the GitHub Action step from the repository.
FAQ
How do I measure the cost?
Run `toolism measure tools.json` or read tools from a server: `toolism measure --mcp "npx -y @modelcontextprotocol/server-github"`.
How do I lock the result in CI?
Create a baseline with `toolism check tools.json -b .toolism/baseline.json --update-baseline`, then run `toolism check` with `--max-increase 5%`.
Does trimming break calls?
Safe rules apply by default, and `--verify` checks the schema in both directions and reverts rules with a found counterexample.
How do I run it without installing?
With `uvx toolism measure tools.json` or by installing through `pipx`.
Is there a GitHub integration?
Yes, a GitHub Action with inputs and outputs and a pre-commit hook.
Discussion
No questions or reviews yet.
Related
CLI toolsA proxy compresses the tool descriptions of a large MCP server so the model spends context only on the calls it needs.
A zero-dependency Python CLI: one catalog of MCP servers and skills for every agent, with only a compact index in context
A CLI for any MCP server: list and call tools, resources and prompts, run mock and proxy modes, guard access and manage agent configs
A CLI installer for eight token-saving tools: rules, hooks, MCP servers and a local proxy for Claude Code, Codex and Cursor.
One MCP gateway instead of dozens of servers: the agent finds a tool on demand and keeps no schemas in context
Lets an agent call MCP and UTCP tools by running code: discover tools, get typed code and run chains instead of dozens of separate calls
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| toolism (this card) | no | 54 | ||
| Token Optimizer | no | 2,964 | general agent token savings; toolism trims tool and MCP schemas while checking call equivalence | |
| schemagate: access-scoped schema selection for text-to-sql | no | not required | 136 | a tool-schema gate; toolism measures and trims schemas and holds the cost in CI |
README in short
Trimming touches only what the model already knows. The author's benchmark reports results for thirteen popular MCP servers, including official ones.