Tool descriptions are part of the context you send to a model. A few wordy definitions can become a recurring input cost, especially when an agent carries the same tool catalog through multiple requests. The goal is not to make every description tiny. It is to remove words that do not help the model choose a tool or supply valid arguments.
Use this numbered pit-stop checklist to shorten your definitions without stripping away the rules that make tool calls reliable.
1. Record the tool-definition baseline
Save the exact tool definitions your application currently sends, including parameter descriptions and schemas. Measure their token count with a tokenizer appropriate to your target model, or use provider token-counting facilities where available. Character counts are only a rough proxy.
Also record input-token usage from representative requests. Keep the model, conversation history, tool inventory, and settings unchanged during comparisons. Total request usage includes more than tool definitions, so separate the definition estimate from the full-request measurement.
2. Give each tool one clear selection sentence
A useful description tells the model what the tool does and when to choose it. Remove introductory language, repeated tool names, and promises such as “powerful” or “easy to use.” Those words rarely change a tool-selection decision.
Before: “This tool allows you to search through the company's internal documentation to find documents that are relevant to the search query provided by the user.”
After: “Search internal documentation by query; return matching excerpts and document identifiers.”
The shorter version preserves the searchable resource and clarifies the result. Do not add behavior merely to make the sentence sound complete: every claim must match the implementation.
3. Let parameter schemas carry structural rules
Check whether prose repeats information already expressed by types, required fields, or enumerated values. A parameter declared as a required integer usually does not need a description saying that it must be provided as an integer.
- Use enumerated values for fixed choices when your tool interface supports them.
- Keep units explicit: “Timeout in seconds” is more useful than “Timeout value.”
- Document defaults only when the implementation actually applies them.
- Retain semantic limits that the supported schema cannot express.
Verify which schema features your endpoint accepts. A constraint that is unsupported or ignored cannot replace a necessary instruction.
4. Preserve boundaries that prevent costly mistakes
Do not compress away authorization requirements, destructive effects, or distinctions between similar tools. “Delete a project permanently; requires explicit user confirmation” carries more operational value than a paragraph of generic background.
Keep important exclusions, too. If a search tool covers public documentation but not private workspace files, say so. If an identifier must come from a previous lookup, preserve that requirement. Short descriptions should reduce ambiguity, not transfer it into failed calls and retries.
5. Test tool choice and arguments after each edit
Build a small regression set from real tasks. Include a straightforward request, an ambiguous request, a missing required value, a request outside the tool's scope, and a sensitive action requiring confirmation.
Compare selected tools, argument validity, unnecessary calls, and completed tasks. Inspect mistakes rather than relying only on an aggregate success rate. If trimming one sentence causes confusion between two tools, restore the distinguishing detail. Change one definition at a time so regressions have an obvious source.
6. Measure billed usage with realistic conversations
Run the original and revised catalogs through the same conversation samples. Shorter definitions generally reduce raw input tokens, but billed savings depend on pricing, prompt caching, request construction, and any additional retries. Do not assume a percentage reduction in description length produces the same percentage reduction in your bill.
SwiftRelay's per-token billing makes it a practical place to track usage during this cleanup. You can sign up for SwiftRelay and use the small gift credit on a controlled test with Claude Sonnet 5. Keep the relay route and model fixed while comparing revisions.
7. Commit the compact catalog with its tests
Store the revised definitions, baseline measurements, and regression cases together. Review new descriptions for duplicated instructions and missing operational boundaries. Your finish line is a smaller tool catalog that still selects correctly, supplies valid arguments, and respects the original safeguards.