Why should agent tools have clear descriptions?

Agent tools should have clear descriptions because the model often uses those descriptions to understand what each tool does and decide when it should be called.

If tool descriptions are vague or overlapping, the agent is more likely to choose the wrong tool or use the right tool incorrectly.

Tool descriptions guide selection

Imagine an agent has these tools:

• get_order_status
• search_orders
• cancel_order

A clear description might say:

get_order_status: Retrieve the current status of a known order using its order ID.

That description tells the agent both:

• what the tool does
• when it is appropriate

If the user already knows the order ID, this tool is a strong match.

Vague descriptions create ambiguity

Consider these tools:

• get_data
• fetch_info
• lookup_record

Their names and descriptions do not explain what type of information they retrieve.

The agent may choose based on weak similarity rather than actual capability.

Clear descriptions reduce this ambiguity.

Descriptions should explain when to use the tool

A useful description should go beyond repeating the tool name.

Weak:

search_orders: Searches orders.

Better:

search_orders: Find orders when the exact order ID is unknown. Search using customer email, date, or status.

The second description helps the agent understand the situations where the tool is appropriate.

Descriptions can also explain when not to use a tool

This becomes important when tools overlap.

For example:

get_customer: Retrieve one customer when the customer ID is known. Do not use this tool to search by name or email.

search_customers: Find customers by name or email when the customer ID is unknown.

This distinction can prevent incorrect routing.

Clear descriptions improve argument generation

Tool descriptions and parameter descriptions work together.

For example:

customer_id: Internal customer identifier, such as C123. Do not pass an email address.

This prevents the agent from sending:

customer_id = user@example.com

when the tool expects a different identifier.

They help distinguish read tools from action tools

The agent should understand whether a tool only reads information or changes something.

For example:

get_subscription: Read the customer's current subscription. Does not modify the account.

cancel_subscription: Permanently schedules the customer's subscription for cancellation.

Clear action descriptions reduce the chance that an agent performs a state-changing operation when it only needed information.

Important side effects should be stated

If a tool causes a real-world effect, the description should make that obvious.

For example:

send_email: Sends an email immediately to the specified recipient.

That is clearer than:

send_email: Handles email.

The agent needs to know that calling the tool actually performs the action.

Preconditions should be clear

Some tools only work under specific conditions.

For example:

issue_refund: Issue a refund for an existing captured payment. Requires a valid payment ID and an amount not greater than the refundable balance.

This helps the agent decide whether it has enough information before calling the tool.

Similar tools need especially precise descriptions

Suppose an agent has:

• search_web
• search_internal_docs
• search_customer_records

All three perform search, but against different sources.

Descriptions should clearly state:

• what source is searched
• what kind of information is expected
• what permissions apply
• when another search tool is more appropriate

Otherwise the agent may retrieve information from the wrong source.

Good descriptions reduce unnecessary tool calls

If the agent understands a tool's purpose, it is less likely to experiment with several tools unnecessarily.

That can reduce:

• latency
• API cost
• rate-limit usage
• error rate
• extra reasoning steps

Clear tools make workflows more efficient.

Descriptions support safer tool use

For sensitive tools, descriptions can indicate that additional controls exist.

For example:

deploy_production: Deploy a validated release to production. Requires an approved release ID and human authorization before execution.

The actual authorization must still be enforced by the runtime, but the description helps the model reason correctly about the workflow.

Descriptions do not replace enforcement

A good description might say:

Only use for administrators.

But that sentence alone is not security.

The backend must still verify whether the current user is actually authorized.

Tool descriptions guide model behavior.

Deterministic controls enforce permissions.

A good tool description answers four questions

The agent should be able to understand:

1. What does this tool do?
2. When should it be used?
3. What information does it require?
4. What important limitations or side effects does it have?

For similar tools, it can also help to explain when the tool should not be used.

Example

Weak description:

update_order: Updates an order.

Better description:

update_shipping_address: Update the shipping address for an order that has not yet shipped. Requires the order ID and complete new address. Does not change billing information or orders already in transit.

The second version gives the agent enough context to make a much better decision.

In short

Clear tool descriptions help AI agents select the right tool, provide the right inputs, understand limitations, and avoid unnecessary or dangerous actions.

A good description should clearly communicate the tool's purpose, intended use, required context, limitations, and important side effects.