An AI agent acts on the world through tools: functions it can call to look something up, create a record or send a message. Much of the attention goes to the model and the prompt, while the tools themselves are often thin wrappers around existing APIs that were never designed with a language model in mind.
Good AI agent tool design makes an agent more reliable, safer and easier to debug. Poor tool design produces confusing errors that look like model failures.
Name tools for what they do
The model chooses tools largely from their names and descriptions. A tool called get_customer_by_email is clearer than lookup or fetch_data. Clear names reduce the chance of the model picking the wrong tool.
Descriptions should say when to use the tool and when not to. If two tools are similar, explain the difference explicitly.
Keep each tool narrow
A single tool that can do many things, controlled by a mode parameter, is harder for a model to use correctly than several focused tools. Narrow tools are easier to describe, easier to test and easier to secure.
Narrow tools also make permissions simpler. A read-only lookup tool can be granted freely, while a tool that deletes records can be restricted or require approval.
Most agent errors we investigate are not the model being foolish. They are a tool with an ambiguous parameter that the model understandably filled in wrong.
Lena Fischer, Solutions Architect, Engineered With AI
Design parameters carefully
Use clear parameter names, specific types and allowed values where possible. A status parameter that accepts only a defined list is far safer than free text the model has to guess.
Avoid parameters that require the model to remember exact internal identifiers it has not been given. If the model needs an ID, provide a tool that finds it.
Return useful results
Tool outputs should contain what the model needs for its next step, and little else. Returning an entire database record when only two fields matter wastes context and invites confusion.
Structure the output consistently, so the model can rely on the same fields appearing each time.
Write errors the model can act on
When a tool fails, the error message is read by the model. "Error 400" gives it nothing to work with. "No customer found with that email address; try searching by name" tells it what to do next.
Good error messages let agents recover from mistakes on their own, which reduces the number of tasks that need human attention.
Make actions safe by default
Tools that change things should be cautious by default. Draft rather than send, preview rather than delete, and require confirmation for anything irreversible or high-value.
Enforce limits in the tool itself rather than relying on instructions in the prompt. The approach is covered further in access control for AI agents.
Make tools idempotent where possible
Agents sometimes call a tool twice, for example after a timeout. A tool designed so that repeating the same call does not create a duplicate, such as by using a unique request reference, prevents double orders and duplicate messages.
This single design choice avoids a whole class of hard-to-trace problems.
Limit the number of tools
Giving an agent dozens of tools makes selection harder and increases mistakes. Offer only the tools relevant to the task, and group or route requests so each agent sees a manageable set.
If an agent needs many capabilities, consider splitting the work between several focused agents.
Log every call
Record each tool call with its parameters, result and timing. These logs are essential for understanding what the agent did and why something went wrong.
They also reveal which tools are misused most often, pointing to where descriptions or parameters need improving.
Test tools with the model
A tool that works perfectly when called by code may still be misused by a model. Test with realistic tasks and see how the model chooses and uses each tool.
Adjust names, descriptions and parameters based on what you observe, and keep those tests as part of your evaluation set.
Agents misusing their tools?
We will review your tool definitions and redesign the ones causing errors.