{"slug": "a-preferred-way-to-design-tools-for-ai-agents", "title": "A preferred way to design tools for AI agents", "summary": "A developer argues that well-designed tools, not smarter models, are the key to improving AI agent performance, recommending a minimal tool set with clear, non-overlapping functions and a specific system prompt. The approach uses an agent to design tools for another agent, based on a proven method that avoids ambiguous tool names and excessive tool counts, which Anthropic's documentation shows degrade Claude's accuracy beyond 30-50 tools.", "body_md": "# Your Agent Isn’t Dumb, Your Tools Are\n\n### A preferred way to design tools for AI agents\n\nThe 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.\n\nThis 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.\n\n# Why Tools Matter So Much\n\nAn 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:\n\n- **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.\n\n- **Poor descriptions mean the tool never gets used.** The description is the only guidance the agent has for when to call the tool.\n\n- **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.\n\nFor example, consider a ``get_opportunity`\n\n` tool next to ``get_opportunity_health`\n\n`. 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.\n\n# More Tools Don’t Always Mean Better Results\n\nWhen 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.\n\nTool design is where most of the agent’s real intelligence is found, intentionally or not.\n\n# It Starts Before Tools—With the System Prompt\n\nYou 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.\n\nIf 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.\n\n# How to Determine if a Tool Should Exist\n\nPut aside the technical details—the goal is straightforward: given a user’s question, the agent should know exactly which tool to use.\n\nA 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.\n\n# Using an Agent to Design Your Tools\n\nOne surprising aspect of our process is that **we use an agent to build the tools for our agent**.\n\nOnce 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.\n\nThis 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.\n\nA quick example.\n\nFor 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:\n\n- ``get_pipeline_risk_signals(owner, quarter)`\n\n` — deals flagged by stall time, stage regression, or missing next steps\n\n- ``get_account_activity(account_id, since_date)`\n\n` — timeline of field changes, emails, and meetings\n\n- ``get_field_change_history(object_id, field_name)`\n\n` — raw audit trail for a specific field\n\nNotably, 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`\n\n` addresses that case as well—until testing reveals it doesn’t.\n\n# Implement, Then Test for Real\n\nUse 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).\n\nFocus 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.”\n\n# When It’s Wrong, Ask the Agent Why\n\nDon’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.\n\n# Keep Iterating Until Performance Is Stable\n\nRepeat 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.\n\nThis 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.", "url": "https://wpnews.pro/news/a-preferred-way-to-design-tools-for-ai-agents", "canonical_source": "https://www.bolshchikov.com/p/your-agent-isnt-dumb-your-tools-are", "published_at": "2026-07-27 10:32:40+00:00", "updated_at": "2026-07-27 10:52:40.273986+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "ai-products"], "entities": ["Anthropic", "Claude", "Salesforce"], "alternates": {"html": "https://wpnews.pro/news/a-preferred-way-to-design-tools-for-ai-agents", "markdown": "https://wpnews.pro/news/a-preferred-way-to-design-tools-for-ai-agents.md", "text": "https://wpnews.pro/news/a-preferred-way-to-design-tools-for-ai-agents.txt", "jsonld": "https://wpnews.pro/news/a-preferred-way-to-design-tools-for-ai-agents.jsonld"}}