The most common failure I see in agent builds is not the model and not the orchestrator. It is the tool definition. Copilot Studio agent tools get selected by a runtime relevance score, not by a human reading a list, and a definition written like internal documentation produces silent misrouting. This walkthrough takes one tool from a vague definition to one the planner can bind against reliably. By the end you have a repeatable checklist you can apply to every tool on every agent.
If you want the mechanics behind why this works, I covered the scoring behavior in how Copilot Studio tool selection works under the hood. This post is the practical half.
Step 1: Name the tool as a verb phrase
Rename the tool from a system name to an action. SAPQuery tells the planner nothing. GetOpenInvoicesForCustomer tells it exactly which user intents should route here. The name is scored alongside the description, so it is free relevance signal. Do not waste it on the name of the backend system. The trade-off: verb-phrase names are longer and less pretty in your solution explorer. Accept that. You are optimizing for the planner, not the maker portal.
Step 2: Write the description as a retrieval hint
This is where most Copilot Studio agent tools go wrong. The orchestrator scores your description against the user’s actual words, so write it in the vocabulary users type, not the vocabulary your architecture diagram uses.
Bad: Calls the finance API endpoint to retrieve invoice records from the ERP integration layer.
Good: Returns unpaid or overdue invoices for a specific customer. Use when the user asks about outstanding balances, open invoices, what a customer owes, or payment status.
The second version contains the phrases real users produce. Anthropic’s guidance on tool use for Claude lands on the same principle: describe when to use the tool, not how it is implemented. This holds across every function calling stack I have worked with, not just Copilot Studio. If you are thinking about how topic descriptions interact with the same orchestration layer, Stop Copilot Studio Generative Answers From Hijacking Your Topics covers the overlap and where the fix lives.
Step 3: Give parameters binding-friendly names and descriptions
A parameter named id of type string gives the planner nothing concrete to bind against. When the user says “show me what Contoso owes,” the planner has to guess which fragment of the utterance belongs in id. Rename it to customerAccountNumber and describe it precisely: The customer's account number in the format CUST-00000. If the user gives a company name instead, resolve it with SearchCustomerByName first.
That last sentence matters. Parameter descriptions are one of the few places you can teach the planner tool sequencing without writing orchestration logic. Use enums wherever the value set is closed. status as a free string invites hallucinated values; an enum of open, paid, overdue removes the guesswork entirely. The Microsoft Learn documentation for Copilot Studio covers the input schema options, but it will not tell you to write them this defensively. Experience will.
Step 4: Return full state, not a status flag
Design the output for the agent’s next turn, not for a log file. A tool that returns {"status": "success"} leaves the agent with nothing to reason about. If the user then asks “which of those is overdue by more than 30 days,” the agent has no data and either calls the tool again or makes something up. Return the invoice list with dates, amounts, and statuses in the response. Yes, that costs tokens. It is cheaper than a second tool call and far cheaper than a confident wrong answer. I traced several production incidents back to exactly this pattern when I wrote about why agents fail in production after passing testing. The same principle applies at the agent architecture level — as I argued in The Model Is the Cheapest Part of Every Enterprise AI Agent, grounding data and tool design are where reliability is actually won or lost.
Step 5: Test with overlapping intents, not happy paths
Do not test by asking the question the tool was built for. Test the boundaries between tools. If you have GetOpenInvoicesForCustomer and GetOrderHistoryForCustomer, ask something ambiguous like “what’s the situation with Contoso’s account” ten times and watch which tool fires. If routing flips between runs, your descriptions overlap and you need to sharpen the “use when” clauses until they carve up the intent space cleanly. Also test with the wrong entity format on purpose. Give a company name where an account number is expected and confirm the planner chains through the lookup tool instead of stuffing garbage into the parameter.
The finished state
You end up with a tool that has a verb-phrase name, a description written in user vocabulary with explicit “use when” phrases, typed parameters with formats and enums, and an output rich enough to support follow-up questions. Apply the same pass to every tool on the agent and misrouting drops sharply. In my experience, this single pass fixes more agent reliability problems than any prompt engineering on the instructions.
One pitfall to watch: do not keep adding well-designed tools forever. Past roughly 10 to 15 tools on a single agent, the relevance signal gets noisy no matter how clean your definitions are. At that point the fix is splitting the agent, not another description rewrite.
Frequently Asked Questions
How do I write good descriptions for Copilot Studio agent tools?
Write descriptions using the vocabulary your users actually type, not technical or architectural language. Include phrases like ‘use when the user asks about…’ so the orchestrator can match the tool to real user intents. Describing when to use a tool, rather than how it works internally, consistently improves routing accuracy.
Why does my Copilot Studio agent keep routing to the wrong tool?
Tool selection is driven by a relevance score calculated at runtime, not a manual lookup, so vague or technical definitions cause silent misrouting. If your tool names and descriptions are written for developers rather than the planner, the orchestrator cannot reliably match them to user input. Rewriting names as verb phrases and descriptions in plain user language usually resolves the problem.
What is the best way to name tools in a Copilot Studio agent?
Name tools as verb phrases that describe a clear action, such as GetOpenInvoicesForCustomer rather than SAPQuery. The name is scored alongside the description, so it carries relevance signal and should reflect user intent rather than the underlying system or API.
How do I define parameters so a Copilot Studio agent can fill them correctly?
Give each parameter a descriptive name and a clear explanation of what value it expects and where that value comes from in the conversation. A parameter named ‘id’ with no context forces the planner to guess, while a name like ‘customerName’ with a description reduces binding errors and makes extraction from user utterances more reliable.
Leave a Reply