Writing tool descriptions models actually follow
The model chooses a tool from its name, description and inputs, nothing else. Six rules for tool definitions that lead to the right call.
2 min read
When a model chooses a tool, it does not read your code. It reads the tool’s name, its description and its inputs. If those are vague, the model guesses, and guesses are where agents go wrong. Here is how to write tool definitions models follow.
What the model actually sees
name: customer_context
description: Get everything known about one customer before a call:
CRM details, recent email and team conversations.
Use when the user mentions a specific customer or meeting.
inputs: customer (string): the company name or domain
That is the whole interface. Everything the model knows about when and how to use the tool comes from these few lines.
Six rules for tool definitions
1. Name the outcome
customer_context tells the model what it gets. crm_tool_v2 tells it nothing. Prefer a noun for what comes back, or a verb for what happens.
2. Say when to use it
The most useful sentence in a description is the trigger: “Use when the user mentions a specific customer.” It turns a capability into a decision rule.
3. Say when not to use it
If two tools overlap, draw the line: “For general web questions, use web search instead.” One sentence prevents a whole class of wrong calls.
4. Describe every input in plain words
Give each input a meaning and an example format. “customer: the company name or domain, for example acme.com” beats “id: string”.
5. Keep one job per tool
A tool that searches, sends and deletes forces the model to explain its intent through arguments. Separate tools make each decision simple, and let you enable reading without enabling writing.
6. Hide what the model does not need
Endpoints, pagination and authentication belong behind the tool. With Agent200 they live in the connector or workflow, so the definition stays about the task.
Test it like an interface
- Write five requests that should use the tool and five that should not.
- Run them and look at which tools the model chose.
- When it chooses wrong, fix the description first, not the prompt.
Good definitions, fewer tools
The best tool list is short. Group operations that always happen together into one workflow with one clear description, and pass each run() only the tools its task needs. The model makes fewer decisions, and gets more of them right.
Read more about connectors and tools and building workflows.
