Duaer

Guides

How to Write Agent Tool-Calling Prompts in 2027: Stop Models from Calling Tools Wrongly

This guide from the Duaer docs site explains how to write tool descriptions, calling policies, parameter permissions, and regression tests for enterprise AI agents, helping teams cut down on missed calls, wrong tool selection, and incorrect parameters.

Why Tool Calling Is Harder Than Ordinary Prompting

Many teams building agents start by wiring up internal systems: looking up orders, opening tickets, sending emails, updating inventory. Once everything is connected, they often find that the model either fails to call a tool when it should, picks the wrong one, or fills in a parameter with a value that looks plausible but is actually wrong. Engineers tend to start by changing code or adding retries, and only later discover that the root cause is a piece of text almost no one wrote carefully: the tool description and the calling prompt. For an agent, the tool description is its manual. If the manual is vague, the agent has to guess.

In ordinary Q&A, a wrong answer is visible to a person, and a one-sentence fix may be enough. Tool calls work differently. The model's output is a structured request, and an error turns directly into a real action, such as an incorrect refund, a wrong ticket, or a bad data write. A single task often chains several tool calls, so an early mistake can be amplified in later steps. The goal of a calling prompt is therefore not just to make the model say the right thing, but to make it do the right thing at the right moment.

Selection is another difficulty. As the number of tools grows, descriptions start to overlap, and the model begins to waver between 'look up customer' and 'look up order'. These problems are rarely obvious in demos. They surface clearly only once real traffic arrives. For a fuller breakdown of why integration stalls at this stage, from both an organizational and a pipeline perspective, see the article 'Enterprise AI Agent Adoption Challenges in 2027: Why Integration Stalls'.

A Common Mistake: Treating Tool Descriptions as an API Doc Attachment

The most common approach is to paste the backend API documentation straight into the prompt: a function named get_data_v2 with the description 'Get data'. For engineers, that information is enough. For the model, it doesn't explain when to use the tool, when not to, or what the parameters mean in business terms.

The second mistake is describing what a tool can do without saying what it must not do. A refund tool can really issue refunds, but it should not be used for orders outside the after-sales window. Without that boundary written down, the model will take the tool at face value and refund whenever the user asks.

The third mistake is putting every rule into one very long system prompt and hoping the model remembers them all. The more rules there are, the more likely they are to conflict, and the harder they are to maintain. Rules should live as close to the tools as possible, inside the descriptions of the tools they govern.

How to Write Tool Descriptions Properly

A good tool description answers at least four questions: what business problem the tool solves, when it should be called, when it should not be called, and what each parameter means in business terms and what values it can take.

Consider a comparison. A weak version reads: 'query_order: Query an order. Parameter id: order id.' A strong version reads: 'query_order: Given an order number the user has provided, retrieve the order status and shipping information. Use only when the user explicitly provides an order number. If the user gives only a phone number or a name, call find_customer first and do not guess the order number. Parameter order_no: numeric, 11 digits. If the user gives a different format, confirm with the user before calling.'

The difference lies in edge cases. The strong version gives the model a clear path for handling them instead of leaving it to improvise. Tool names should also follow a 'verb plus object' pattern, avoiding semantically vague names such as tool1, process, or handle.

Calling Policies and Parameter Permissions: When to Call, Ask, or Refuse

Descriptions solve problems for individual tools, but a calling policy is also needed to constrain the overall workflow. It is useful to sort tools into three categories. Read-only tools can be called directly. Tools with side effects that can be reversed, such as creating a draft, can be called, but the result should state what was done. Irreversible or high-risk tools, such as payments, deletions, or external sends, must first output a confirmation summary and run only after the user explicitly confirms.

You should also specify what happens when parameters are missing. A common failure is that the model fills in a default value on its own when required information is absent, so the call succeeds but acts on the wrong object. The prompt should state clearly that when a required parameter is missing, the model must not fabricate it and must ask the user instead. This rule looks simple, but it blocks a large number of silent errors.

Prompts can reduce the error rate, but they cannot replace program-level validation. Parameters generated by the model must be checked for type, range, enum values, and permissions. When validation fails, the specific error should be returned to the model so it can correct the call, rather than reporting success. Return values should also be truncated and structured so that large raw JSON payloads do not fill the context and derail later reasoning.

Permissions matter most of all. A prompt can tell the model 'do not query other departments' data', but the real permission boundary must be enforced by identity and role controls at the tool layer. Relying on the prompt for security is the starting point of many incidents.

How to Measure Results, and What to Do This Week

Many teams' evaluation amounts to 'I tried it a few times and it seemed fine'. A more reliable approach is to prepare a set of real tasks covering normal cases, edge cases, and adversarial cases, such as users requesting operations they are not authorized to perform. Each task should be labeled with the expected tool, the expected parameters, and the expected behavior, whether that is a refusal or a follow-up question. Every time a description or prompt is changed, run the full test set again.

Five core metrics are worth tracking: whether the tool was called when it should have been, whether the right tool was selected, whether parameters were valid and semantically correct, whether the model asked follow-up questions when parameters were missing, and whether unauthorized or high-risk operations were blocked. These metrics should be tracked per tool, because one vague description usually affects only one or two tools, and an overall average can hide the problem.

Prompts themselves should be under version control. Changing a single word can shift calling behavior across the board, and without records, problems are hard to trace. The same logic applies to prompt versioning; for related practices, see the article '2027 Prompt Version Control: How Untracked Prompts Break Enterprise AI'. If you want to keep tool descriptions, test tasks, and version history side by side in one place, you can set up this workflow directly in Duaer and see how results change after each edit.

If you want to start this week, pick the three most frequently called and highest-risk tools in your system, rewrite each description one by one, and add two items: when not to use the tool, and what to do when a parameter is missing. Then run a regression with twenty real tasks. Doing just this often surfaces most of the major calling errors.

If your team wants to make this systematic, you can sign up for a trial at https://www.duaer.com. Start by running the workflow with one toolset, then decide whether to expand the scope.

If your team is in the middle of tool integration or unstable tool calling, we can provide a free implementation roadmap for this scenario. Tell us about your situation and we will send you a written roadmap: https://api.duaer.com/form/1fea7709-3f8a-47f7-b4e3-eb5fb90e3213

Questions

How should I write tool descriptions for an AI agent so the model doesn't misuse them?

A tool description should at least explain the business purpose, when the tool should be called, when it should not be called, and what each parameter means and which values it accepts. For edge cases, give the model an explicit handling path. For example, if the order number is missing, it should call a customer lookup tool first instead of guessing.

How can I tell whether an AI agent's tool calling is reliable?

Prepare a set of real tasks covering normal, edge-case, and unauthorized scenarios, label the expected tool, parameters, and refusal or follow-up behavior, and rerun them after every change to a description or prompt. Track metrics per tool, including call timing, tool selection, parameter correctness, follow-up questions on missing parameters, and blocking of high-risk operations.

Can I restrict an AI agent's tool permissions with prompts alone?

No. Prompts can lower the error rate, but the real permission boundary must be enforced through identity and role controls at the tool layer, with type, range, enum, and permission validation applied to every model-generated parameter. Relying entirely on prompts for security is a common source of incidents.