Tool Naming for AI Agents: Clear Names, Descriptions and Schemas
Name AI agent tools clearly, write descriptions that guide tool choice, design schemas that reject vague calls, and review all three before release.

Tool naming for AI agents means giving each action a clear name, a short description of when to use it, and an argument schema that rejects incomplete or ambiguous input. The model chooses tools by reading this text, so an overlapping name or a description that leaves out side effects produces wrong actions even when the underlying code works. Review names, descriptions and schemas as one unit before release, and test them with requests that should and should not trigger each tool.
Key takeaways
- Give each tool one verb-and-object name that matches one business action, so the model can match a request without guessing.
- Write the description as a selection guide: when to use the tool, when not to, what it returns and whether it changes anything.
- Use argument schemas for the checks the model cannot make on its own: typed fields, fixed choices, required values and units.
- Review names, descriptions and schemas together, and test which tool the model picks for realistic requests, including requests that need no tool.
- Release tool changes as versioned sets with a rollback path, the same way you would release a prompt change.
Why tool names decide actions before any code runs
A harness shows the model a list of available tools, each with a name, a description and parameter definitions. On every step the model reads that list and either picks one action or none. The code behind a tool can be correct and still be called at the wrong moment, because the decision was made earlier, in text. For this reason, tool design belongs in the same review as access rights and approval rules, not in a separate technical cleanup later. If you want background on how tool calls fit into the working loop, the plain explanation of tool calling is a useful starting point.
Illustrative scenario: a support team exposes two tools, one called lookup_customer and one called get_account. Both return a customer record. When a user asks whether a specific invoice has been paid, the model picks lookup_customer, which returns contact details but no payment status. The fix is not a longer prompt. It is a rename and a rewrite: a tool called find_invoice_payment_status, described as the tool for paid or unpaid questions about one invoice number, and a customer tool whose description says it returns contact details only.
How do you name a tool so the model picks it reliably?
A tool name should describe exactly one action on one kind of object. The model treats names as literal labels, so vague names force it to guess. Apply these rules across the whole registry:
- Start with a verb that matches the business action, such as find, create, update, cancel or send.
- Name the object the action touches, such as invoice, appointment, quote or shipment.
- Avoid generic verbs such as handle, process, manage or run, because they let the model assume almost anything.
- Keep one job per tool. If the name needs the word and to be understood, split the tool into two.
- Use one naming pattern everywhere, and make sure no two tools could plausibly answer the same request.
Treat released names as stable. A rename changes the behavior your tests measure, so if a name must change, record it as a new registry version and rerun the selection tests before rollout.
What should a tool description say?
The description is the selection guide the model reads before it commits to an action. A useful description covers five points: what the tool does, when to use it, when not to use it, what it returns and whether it changes data or triggers an external message. Write it the way you would brief a new staff member who has never seen your systems. Avoid marketing language such as powerful or advanced, since they add no decision information.
A description for the payment tool might state that it reads the payment status of one invoice when the user gives an invoice number, that it should not be used to look up contact details, that it returns status and amount due, and that it is read only. That single paragraph prevents most wrong picks. Mention approval requirements in the description too, so the model does not assume that a read tool can also send a reminder.
How do argument schemas stop vague calls?
The schema is the part of the tool definition that the harness can check. The model fills in the fields, the harness validates the call before anything runs, and an invalid call returns a clear error the model can correct. Without a schema, a vague request can turn into a guessed identifier or a date in the wrong format, and the failure may only appear after an action has run. Build schemas with these habits:
- Type every field as text, integer, boolean or a fixed set of values.
- Use enumerations for choices such as status, channel or region, so the model cannot invent a new value.
- Mark required fields explicitly, and keep optional fields to a minimum.
- Put units in the field name, such as days_until_due, rather than leaving a bare number.
- Prefer stable identifiers, such as an invoice identifier, over free-text names when the source system accepts them.
- Set limits on list lengths and text sizes, so one call cannot return or send unbounded content.
Keep the schema descriptions short but precise. A field described only as a date invites confusion about format and time zone, while a field described as a due date in ISO 8601 calendar format leaves little room for error. The article on structured outputs covers how schemas act as a contract the harness can validate.
A schema stops malformed calls. It does not decide whether the caller is allowed to make them, which belongs in the authorization rules of the harness.
A release review for tool names, descriptions and schemas
Run this review before any registry change reaches live work. It takes a single reviewer less time than a meeting, and it catches the problems that are expensive to find in production.
- Export the full tool list exactly as the model will receive it, including names, descriptions and schemas.
- Check each name against the one-action rule, and flag any pair of tools whose verbs and objects overlap.
- Read each description aloud and confirm that it states use, non-use, return values and side effects.
- Confirm that every write or external action has an approval boundary defined outside the description, so the description is never the only control.
- Validate each schema with a sample valid call and several invalid ones, and confirm that the harness rejects the invalid calls with a readable error.
- Run the selection tests described in the next section and record the results.
- Approve the change, store it as a numbered registry version and keep the previous version ready for rollback.
How do you test which tool the model chooses?
Test the choice, not only whether a tool works. Write a small set of requests in the words real users use, group them by the tool they should trigger, and add requests that should trigger no tool at all. Run the set against the current registry and record the tool and arguments the model selected. Wrong picks point to naming or description problems, and invalid arguments point to schema problems. OpenAI's guide to evals describes this pattern of writing cases, running them and grading outcomes, and the same logic applies to tool selection.
Start small and grow the set from real failures, rather than writing a large suite before you have seen how the agent behaves. Rerun the set after every registry change, and keep the results with the version record. If the registry keeps growing and wrong picks keep appearing, narrow the tool list before adding descriptions. The article on tool allowlists explains how to begin with fewer tools and widen only with evidence.
How Be Human handles tool registration
Be Human's managed approach starts with the role definition. The first engagement names one useful role, the memory and tools it needs and the approval boundary for each action, so tool names and descriptions are written from a defined list instead of from a catalog of everything the systems can do. The tool registry is reviewed with the business owner who will judge outcomes and with a technical reviewer who checks schemas, permissions and logging, then released as a versioned set. Managed operations continue after release with recurring selection tests, permission reviews whenever a tool changes, and incident response when a wrong tool causes a problem. Changes go through controlled releases rather than direct edits to live work. If you are not sure which repetitive task is the right first one to hand to an agent, take the free Be Human AI diagnostic to find that first task.
Frequently asked questions
Should every tool name follow the same pattern? Yes. A single pattern across the registry makes overlaps easier to spot in review and keeps logs readable for the people who investigate problems. Choose a verb and object form, apply it to every tool, and treat exceptions as release blockers. The exact style matters less than the fact that your team can keep it consistent.
How many tools should one agent receive? Give the agent only the tools its role needs. Each extra tool is another option the model must weigh, and more options make wrong picks more likely. Start with a short list, test it, and add a tool only when the tests show a real missing capability.
Can a better description fix a poorly designed tool? Sometimes it helps, but a description cannot repair a tool that performs two jobs or accepts unclear inputs. If two actions share one tool, split them into two tools with separate names. If a field is ambiguous, change the schema, and use the description to clarify when to choose the tool rather than to hide the design problem.
Who should review tool names before release? The review needs two perspectives: someone who knows the business process and can judge whether each name and description matches real work, and someone who knows the harness and can check schemas, permissions and logging. Store the review record with the registry version so that a later change can be traced back to the decision behind it.
Your next step
See where an AI agent fits in your company first.
Take the free Be Human AI diagnostic. A few questions about your work show which task to hand to an agent first, what it needs to know and where a person approves.
Be Human editorial guidance. Examples are illustrative unless explicitly attributed. Sources provide background; implementation choices depend on your workflow.


