A preferred way to design tools for AI agents

The gap between an AI answer and a human one rarely comes from intelligence; it’s about detail. A clear, specific answer based on real data is better than a fluent guess. A smarter model can help, but well-designed tools are what truly bridge that gap.

This post outlines an approach that has worked for me in designing tools for agents. It’s not the only way to do this, but it has proven effective across various agents, making it my preferred method.

Why Tools Matter So Much

An agent doesn’t reason over raw data; it works with the interface you provide to that data. Tool names, descriptions, and parameters all shape the model’s decisions each time. Here are a few specific failure modes that can arise:

• Ambiguous tools lead to unclear decisions. If two tools can answer the same question, the agent has to guess, and it will guess wrong a significant amount of the time.

• Poor descriptions mean the tool never gets used. The description is the only guidance the agent has for when to call the tool.

• Granularity is a tradeoff. A tool that accepts raw SQL puts precision back on the model and invites bad queries. Having one tool per object type works well until you have over 50 types and the agent has to choose between very similar options for each call. There’s no one-size-fits-all granularity; it depends on your specific domain.

For example, consider a get_opportunity tool next to get_opportunity_health. This distinction may be clear to a human who understands the data model but seems like the same thing to a model trying to decide which tool to use. This can lead to unpredictable calls, sometimes missing the health update the user requested. The usual fix is to combine the two tools or rename them for clarity.

More Tools Don’t Always Mean Better Results

When an agent overlooks something, the instinct is to add another tool. However, this instinct has limits. Anthropic’s tool-use documentation shows that Claude’s accuracy in selecting tools drops when the number exceeds about 30 to 50. Beyond that, each new tool competes with nearby tools for the agent’s attention instead of expanding its capabilities. The goal should be to have the smallest set of tools that effectively address your real questions.

Tool design is where most of the agent’s real intelligence is found, intentionally or not.

It Starts Before Tools—With the System Prompt

You can’t create effective tools without having a strong system prompt. The prompt defines who the agent is, what domain it operates in, and what it should expect to be asked. Tools serve this purpose, not the other way around.

If you skip this step, it leads to bloat. A vague prompt like “help users with their Salesforce data” makes everything in the schema seem relevant. A specific prompt, such as “help revenue teams identify at-risk pipelines and explain account changes,” quickly clarifies what matters—risk signals and change history, rather than generic CRUD operations. A well-defined prompt helps set clear tool boundaries almost effortlessly, but only if it is specific enough to establish them.

How to Determine if a Tool Should Exist

Put aside the technical details—the goal is straightforward: given a user’s question, the agent should know exactly which tool to use.

A useful test is this: can you identify the question this tool answers that no other tool answers as well? If you can’t, don’t add it yet—wait for a real question to show the need for it. Terms like “it’s in the schema” or “the endpoint exists” aren’t sufficient justifications. Tools added for those reasons often end up sitting unused or clashing with others later on.

Using an Agent to Design Your Tools

One surprising aspect of our process is that we use an agent to build the tools for our agent.

Once you have a solid system prompt and a good set of example questions, provide both to an LLM along with your data structure—such as JSON schema, DB schema, or API spec—and ask it to suggest tools that could answer those questions.

This works because the model doing the design thinks like the agent that will eventually use the tools. It simulates the decision-making process, making it better at identifying ambiguities or gaps that a human might overlook while designing from a schema alone.

A quick example.

For a RevOps agent dealing with Salesforce, with a prompt about pipeline health and account risk, and questions like ”which deals are at risk this quarter,” ”what changed on Acme Corp recently,” and ”why did this opportunity’s stage change,” a reasonable first draft includes:

• get_pipeline_risk_signals(owner, quarter) — deals flagged by stall time, stage regression, or missing next steps

• get_account_activity(account_id, since_date) — timeline of field changes, emails, and meetings

• get_field_change_history(object_id, field_name) — raw audit trail for a specific field

Notably, the third question highlights the need for field-level history, which is a different lookup than account-level activity. If you design only from the schema, you might mistakenly assume that get_account_activity addresses that case as well—until testing reveals it doesn’t.

Implement, Then Test for Real

Use two types of questions: those the tools were designed for (which should work immediately) and new ones the agent hasn’t encountered (this is the true test, revealing whether the tools can generalize or if you’ve just built a lookup table).

Focus on how the agent arrives at answers, not just whether it gets them right. There are three potential errors: using the wrong tool, using the right tool but with incorrect parameters, or chaining together multiple tools when one well-designed tool should suffice. Each type of error points to a different fix—description, parameters, or granularity—so avoid grouping them all as just “the agent got it wrong.”

When It’s Wrong, Ask the Agent Why

Don’t just fix the tool and move on—ask the agent what could have helped it answer correctly. It can often pinpoint exactly what’s wrong: a description that is unclear next to a neighboring tool, a parameter that needs an example, or two tools that should be merged. The agent has direct insight into its decision-making process that you, reading the transcript later, won’t have.

Keep Iterating Until Performance Is Stable

Repeat the cycle—implement, test known and new questions, diagnose with the agent’s assistance, and refine—until you reach a real standard, not just a feeling. Keep track of “right tool, right parameters, right answer” for a new set of questions in each round. When that rate stays steady, you’re finished—not because the agent is perfect, but because you’ve stopped encountering tool-design issues and are instead facing isolated edge cases, which is a smaller problem.

This process isn’t a one-time design. It resembles product iteration more than writing an API specification: ship, observe actual behavior, refine. The key difference is that your most valuable design partner in that process is the agent itself.