AI agents are often evaluated by whether they complete a task successfully. If the agent calls the right tools, produces the expected result, and finishes the workflow, the system is considered useful.
But there is another metric that is easy to overlook: how many tokens did the agent consume to get there?
An agent can successfully complete a task while spending far more tokens than necessary because its tools are poorly described.
A vague tool description can cause the model to repeatedly inspect schemas, choose the wrong tool, retry failed calls, request unnecessary information, or generate verbose arguments. Across thousands of agent executions, this creates measurable cost and latency.
For developers building production AI agents, tool descriptions are therefore not just documentation. They are part of the agent's execution interface.
This article explains how to measure token waste caused by poor tool descriptions, how to design better tool metadata, and how to build an evaluation process that measures both task success and efficiency.
Why Tool Descriptions Matter
An AI agent normally receives information about the tools it can use.
A simplified tool definition might look like:
{
"name": "get_customer",
"description": "Gets customer information.",
"parameters": {
"type": "object",
"properties": {
"id": {
"type": "string"
}
},
"required": ["id"]
}
}
The description looks reasonable, but it leaves several questions unanswered.
The agent does not know:
Whether
idis a database ID or email address.Whether the tool returns the complete customer record.
Whether inactive customers are included.
Whether the tool should be used before another customer-related operation.
Whether there is a more appropriate tool for a specific lookup.
A better description provides useful operational context without becoming unnecessarily large.
For example:
{
"name": "get_customer",
"description": "Retrieve one customer by their unique customer ID. Use this when the customer ID is already known. Do not use it for email-based searches.",
"parameters": {
"type": "object",
"properties": {
"customerId": {
"type": "string",
"description": "The unique customer ID."
}
},
"required": ["customerId"]
}
}
The second description is more precise.
However, there is an important optimization principle:
More description does not automatically mean better description.
The objective is to provide the information the model needs to make a good tool decision with minimal unnecessary context.
What Is Token Waste?
Token waste is the amount of additional model input and output generated because the agent lacks enough useful information to make an efficient decision.
Consider a simple workflow:
User request
|
v
Agent chooses tool
|
v
Tool call fails
|
v
Agent retries
|
v
Agent chooses another tool
|
v
Tool succeeds
The task eventually succeeds, but the agent has generated extra reasoning and tool interactions.
A more efficient workflow might be:
User request
|
v
Correct tool selection
|
v
Successful tool call
|
v
Final response
The difference can be measured.
A useful metric is:
Token Waste =
Actual Tokens - Baseline Tokens
where the baseline represents the tokens required by a well-designed tool configuration for the same task.
Separate Tool Tokens From Task Tokens
When measuring efficiency, distinguish between tokens caused by the task itself and tokens caused by tool design.
For example, a complex task might naturally require substantial reasoning.
That does not necessarily mean the tool descriptions are inefficient.
Track at least:
| Metric | Meaning |
|---|---|
| Input tokens | Tool definitions, conversation, context |
| Output tokens | Agent-generated responses and tool calls |
| Tool-call count | Number of tool invocations |
| Failed calls | Calls rejected or unsuccessful |
| Retry count | Repeated attempts |
| Task completion | Whether the task succeeded |
| Time to completion | End-to-end latency |
| Cost | Estimated model usage cost |
This gives a more useful picture than token count alone.
Tool Descriptions Are Part of the Context Window
Every tool definition consumes input tokens.
Suppose an agent has 30 tools and each description is several hundred tokens.
The model may receive thousands of tokens before it even begins solving the user's task.
For example:
30 tools
×
250 description tokens
=
7,500 input tokens
That context is supplied repeatedly across agent requests depending on the architecture.
Now imagine a system with:
100 tools
×
500 tokens
=
50,000 tokens
The tool catalog itself becomes a significant portion of the context.
This can increase cost and make tool selection harder.
Poor Descriptions Create Selection Errors
Consider these tools:
search_customer
find_customer
lookup_customer
get_customer
query_customer
If their descriptions are vague, the model has little information to distinguish them.
For example:
"Searches for a customer."
"Finds customer information."
"Looks up customer details."
"Gets customer data."
"Queries customer records."
These descriptions overlap heavily.
The agent may select the wrong tool and discover the problem only after executing it.
Better descriptions explain the distinguishing behavior:
search_customer:
Search customers by name, email, or partial text.
get_customer:
Retrieve a single customer using an exact customer ID.
get_customer_orders:
Retrieve orders belonging to a known customer ID.
find_customer_by_email:
Find exactly one customer using an email address.
Now tool selection requires less ambiguity.
Measure Tool Selection Accuracy
Before optimizing tokens, measure whether the agent selects the correct tool.
Create a test dataset:
Task 1:
Find customer by email.
Task 2:
Retrieve customer by ID.
Task 3:
List customer's recent orders.
Task 4:
Search customers by name.
Record:
Expected tool
Actual tool
Number of attempts
Success/failure
Input tokens
Output tokens
For example:
| Task | Expected | Actual | Attempts |
|---|---|---|---|
| Email lookup | find_customer_by_email | find_customer_by_email | 1 |
| ID lookup | get_customer | search_customer | 2 |
| Order lookup | get_customer_orders | get_customer | 2 |
| Name search | search_customer | search_customer | 1 |
The second and third cases indicate tool-description or tool-selection problems.
Measure Retry Waste
A failed tool call is one of the clearest signals of inefficiency.
Suppose the agent produces:
Tool call 1: Invalid parameter
Tool call 2: Missing required field
Tool call 3: Correct request
The agent completed the task, but two unnecessary calls occurred.
Track:
Retry Rate =
Failed Tool Calls / Total Tool Calls
A falling retry rate after improving descriptions is a strong indication that the changes are working.
Measure Tool-Call Efficiency
Another useful metric is:
Tool Call Efficiency =
Successful Required Calls / Total Calls
Consider two agents completing the same task.
Agent A
8 tool calls
5 successful
3 failed
Agent B
5 tool calls
5 successful
Agent B is more efficient even if both agents eventually produce the correct result.
This metric becomes particularly important for expensive tools such as database queries, external APIs, and cloud operations.
Poor Parameter Descriptions Also Cause Waste
Tool-level descriptions are only part of the problem.
Parameter descriptions matter too.
Consider:
{
"customerId": {
"type": "string"
}
}
The model has no explanation of what the value represents.
A better definition is:
{
"customerId": {
"type": "string",
"description": "Unique customer ID returned by the customer service. Do not pass an email address."
}
}
This can prevent invalid calls.
For enumerated values, provide the accepted values explicitly:
{
"environment": {
"type": "string",
"enum": ["development", "staging", "production"],
"description": "Deployment environment. Use development unless the user explicitly requests another environment."
}
}
The schema itself provides structure, while the description provides decision-making context.
Avoid Overloaded Tools
One tool that does everything may appear convenient:
manage_customer
with parameters such as:
operation
customerId
email
status
orderId
action
environment
This can create significant ambiguity.
The agent must determine which combination of parameters corresponds to the desired operation.
Smaller, focused tools can make tool selection easier:
get_customer
search_customer
update_customer
delete_customer
get_customer_orders
However, splitting every possible operation into separate tools is not automatically better.
Too many tools create another problem: tool catalog overload.
The right design is a balance between tool granularity and tool discoverability.
Tool Names Should Carry Meaning
Tool names are part of the model's decision context.
Compare:
execute
process
run
handle
operation
with:
search_customer_by_email
create_invoice
get_order_status
cancel_subscription
The second group communicates intent more clearly.
A descriptive name reduces the amount of reasoning the model needs to infer what the tool actually does.
A good naming convention should be consistent across the entire tool catalog.
Describe When Not to Use a Tool
This is one of the most useful patterns for agent tool design.
Instead of only describing what a tool does:
Retrieves customer information.
also explain important exclusions:
Retrieve one customer by exact customer ID.
Do not use for email searches; use find_customer_by_email instead.
This prevents competing tools from being selected for the wrong task.
Negative guidance is especially valuable when two tools have similar names or overlapping functionality.
Use Examples Carefully
Examples can help the model understand tool usage.
For example:
Use when:
- The user provides an exact customer ID.
Do not use when:
- The user provides only an email address.
However, examples also consume tokens.
Do not add dozens of examples to every tool.
Use examples where the expected behavior is difficult to express through the schema alone.
Measure Before and After
Suppose you have a baseline tool definition.
Record:
Average input tokens: 8,200
Average output tokens: 1,900
Average tool calls: 6.2
Average failed calls: 1.4
Task success rate: 91%
After improving the descriptions:
Average input tokens: 6,900
Average output tokens: 1,500
Average tool calls: 4.3
Average failed calls: 0.5
Task success rate: 96%
The important result is not simply that token usage decreased.
Task success improved while tool-call count and failed calls decreased.
That is a much stronger optimization.
Build an A/B Evaluation
Create two tool configurations.
Version A
Poor or existing descriptions
Version B
Improved descriptions
Run the same task dataset against both.
For example:
| Metric | Version A | Version B |
|---|---|---|
| Task success | 91% | 96% |
| Avg. tool calls | 6.2 | 4.3 |
| Failed calls | 1.4 | 0.5 |
| Input tokens | 8,200 | 6,900 |
| Output tokens | 1,900 | 1,500 |
| Avg. latency | 8.4s | 6.1s |
These numbers are illustrative; real measurements should come from your own workload.
The important methodology is to compare the same tasks under controlled conditions.
Build a Token Efficiency Score
You can create a simple internal metric:
Token Efficiency =
Successful Tasks / Total Agent Tokens
However, this can hide important differences.
A better evaluation combines several dimensions:
Agent Efficiency Score =
Task Success
+
Tool Selection Accuracy
+
Low Retry Rate
+
Low Token Usage
+
Low Latency
Do not optimize token usage independently from correctness.
An agent that saves tokens by skipping necessary validation is not more efficient.
Measure Tool Description Overhead
Tool definitions themselves should be measured.
For each tool, record:
Tool name
Description token count
Parameter token count
Schema token count
Total definition tokens
Then calculate the catalog size:
Total Tool Context =
Sum of all tool definition tokens
This can reveal unexpected overhead.
For example:
Tool A: 120 tokens
Tool B: 340 tokens
Tool C: 890 tokens
Tool D: 1,100 tokens
Tool D deserves investigation.
A long description may be justified for a complex operation, but it should not become long simply because the tool's behavior is poorly designed.
Avoid Repeating Information
A common mistake is repeating the same information at multiple levels.
For example:
Tool:
"Creates a customer."
Parameter:
"Customer name for the customer being created."
Example:
"Create a customer using the customer name."
The same concept appears three times.
Use the tool description for the operation and parameter descriptions for parameter-specific semantics.
This keeps the schema compact.
Use Structured Descriptions
A consistent format makes tool definitions easier to understand.
For example:
Purpose:
Retrieve one customer by exact ID.
Use when:
The customer ID is known.
Do not use when:
The user provides only an email address.
Returns:
Customer profile and account status.
Not every tool needs all four sections.
For complex tools, however, this structure can be clearer than a large paragraph.
Dynamic Tool Selection Can Reduce Context
Large agent systems do not always need to expose every tool to the model.
Instead, tools can be grouped.
For example:
Customer tools
Order tools
Billing tools
Infrastructure tools
Reporting tools
The system can first identify the relevant domain and expose only the necessary tools.
Conceptually:
User request
|
v
Tool domain selection
|
+--> Customer tools
|
+--> Order tools
|
+--> Billing tools
If an agent receives only the tools relevant to the current task, the tool catalog itself becomes smaller.
This can reduce context consumption and tool-selection ambiguity.
Do Not Optimize Descriptions in Isolation
A tool description is part of a larger interface.
Token waste can come from:
Poor tool name
Poor description
Ambiguous parameters
Too many tools
Overlapping tools
Poor error messages
Missing validation
Incorrect tool output
For example, improving a tool description may not solve a problem if the tool returns an unclear error such as:
Invalid request.
A better error might say:
customerId must be a UUID. The supplied value was an email address.
Use find_customer_by_email when searching by email.
The agent receives useful information without needing another discovery step.
Optimize Tool Errors Too
Tool errors are part of the agent's context.
Poor:
Error: request failed.
Better:
Validation failed: orderId is required.
Even better when appropriate:
Validation failed: orderId is required.
The user has not provided an order ID. Ask for the order ID before retrying.
Useful errors reduce repeated attempts.
However, avoid exposing sensitive implementation details or internal credentials in tool errors.
Measure Cost at Scale
A small token difference can become significant at high volume.
Suppose an agent performs:
100,000 tasks/month
and poor tool descriptions cause an additional:
1,000 input tokens/task
That results in:
100,000 × 1,000
=
100,000,000 additional input tokens
The exact financial impact depends on the model and pricing structure, but the engineering lesson is straightforward:
Small inefficiencies become infrastructure costs at scale.
Token optimization therefore belongs in production observability, not only during experimentation.
Add Token Metrics to Agent Observability
For every agent execution, collect metrics such as:
request_id
agent_id
task_type
model
input_tokens
output_tokens
tool_count
failed_tool_count
retry_count
latency
task_result
Avoid storing sensitive prompt or tool content unnecessarily.
Aggregated metrics can then identify patterns.
For example:
Task: Customer Support
Average tool calls: 3.1
Retry rate: 4%
Task: Infrastructure Diagnostics
Average tool calls: 9.7
Retry rate: 21%
The infrastructure workflow may have poor tool definitions or overly complex tool interactions.
Common Mistakes
Making Every Description Extremely Long
Long descriptions increase context usage and can make the relevant information harder to identify.
Using Vague Tool Names
Names such as execute, process, and manage provide little information.
Duplicating Tools
Several tools that perform nearly the same operation create selection ambiguity.
Omitting Parameter Semantics
A schema that says only "type": "string" often leaves important decisions unspecified.
Ignoring Failed Tool Calls
A successful final answer can hide multiple unnecessary retries.
Optimizing Tokens Before Correctness
Reducing context size at the cost of task accuracy is not a useful optimization.
Exposing Every Tool to Every Agent
Large tool catalogs increase both context size and selection complexity.
Ignoring Tool Errors
Poor error messages can force the agent into repeated attempts.
A Practical Evaluation Workflow
A production evaluation can follow this process:
1. Define representative tasks
2. Capture the existing baseline
3. Measure tool definitions
4. Measure token usage
5. Measure tool selection accuracy
6. Identify failed calls and retries
7. Improve names and descriptions
8. Improve parameter definitions
9. Improve tool errors
10. Run the same benchmark again
11. Compare correctness, cost, and latency
12. Keep only changes that improve the overall result
This makes tool design measurable rather than subjective.
Frequently Asked Questions
Does a longer tool description always improve agent performance?
No. A description should contain the information required for correct tool selection and usage. Unnecessary detail increases context usage and can make important information harder to find.
What is the easiest way to identify token waste?
Start by measuring failed tool calls, retries, total tool calls, and input tokens for the same set of representative tasks.
Should I create one tool per operation?
Not necessarily. Too few tools create ambiguity, while too many tools increase catalog size and selection complexity. Tools should have clear, distinct responsibilities.
Are parameter descriptions really important?
Yes. Parameters often contain the ambiguity that causes invalid tool calls. Clear descriptions can tell the model what a value represents, what format is expected, and when a parameter should not be used.
Should tool errors be included in token-efficiency measurements?
Yes. Tool errors become part of the agent context and can directly cause additional calls and token consumption.
Is fewer tokens always better?
No. The goal is efficient task completion, not minimum token usage. A slightly larger context that significantly improves correctness may be preferable to an extremely compact but ambiguous tool definition.
Conclusion
Tool descriptions are easy to treat as documentation, but in an AI agent they are part of the runtime interface between the model and the application. Poor descriptions can cause wrong tool selection, failed calls, retries, unnecessary reasoning, higher latency, and increased token consumption.
The right way to optimize them is to measure the complete workflow. Track task success, tool-selection accuracy, failed calls, retries, token usage, latency, and tool-definition overhead. Then compare the baseline against improved tool names, descriptions, parameter schemas, error messages, and tool catalogs.
The best tool interface is not the one with the most documentation. It is the one that gives the agent enough precise information to make the correct decision without forcing it to discover basic semantics through trial and error.
For production AI systems, token efficiency should therefore be treated as an engineering metric alongside correctness, reliability, latency, and security.
Join the conversation! Your thoughts help the community grow.