Refine tool selection with descriptions
An added tool helps only when the agent calls it for the right requests and leaves other requests to knowledge or other tools. In this unit, you learn how to refine the tool's name, its description, and your agent's instructions to guide that choice, and how to check the result in Preview.
Describe the tool for its job in your agent
The enhanced orchestration runtime uses a tool's name and description to decide when to invoke the tool. A default name and description tell the orchestrator what the SharePoint connector does in any agent. They don't tell it that, in your help agent, this tool answers an employee who asks where a request stands, or submits a new request.
To change the wording, select the tool in the components panel on the Build tab to open the Tool details dialog. In the Details panel, update the name and description, and then select Save.
A name and description that guide selection cover these elements:
- A specific name: State the tool's job, such as "Create support ticket" instead of "Ticket tool."
- When to use it: Name the kind of request the tool handles.
- What it needs: Name the input the agent must have before it calls the tool, such as a request number.
- What it returns: State what comes back, so the agent knows what it can report to the user.
- What it doesn't do: Set a boundary that separates the tool from similar options.
When one connector tool provides more than one action, as it does in your help agent, write the description so it states when each action applies. The following table compares a generic description with one written for the help agent.
| Element | Generic | Refined for the help agent |
|---|---|---|
| Name | SharePoint | Equipment request status and submission |
| Description | Works with SharePoint lists. | Look up the current status of an equipment request by its SharePoint item ID, or create a new request after the employee confirms the details, in the equipment requests list. Use for questions about a request the employee is authorized to view and for new requests. Returns the item ID and status for a lookup, or the new item ID for a submission. Doesn't answer equipment policy questions. |
The refined description names both jobs and the input each one needs, and its boundary sentence sends policy questions elsewhere.
Keep the description accurate to what the tool does. Before you save, compare the returned values that the description names with the Outputs panel, so that the description promises only what the tool actually returns.
Learn more in Add a tool to an agent.
Separate overlapping tools and knowledge
Vague descriptions can prevent the orchestration runtime from selecting a tool, and overlapping descriptions leave it without a clear way to tell two tools apart. Suppose you later add a second tool that returns details about equipment assets, and both tools carry a description such as "Works with equipment." A message like "Where's my dock request?" then matches both descriptions equally well. Scope each description to the records it works with, such as requests or assets, so the difference is explicit.
The same overlap can happen between a tool and knowledge. Your equipment policy documents are knowledge sources, and grounded search over them answers policy questions. A lookup described as "Answers questions about equipment requests" reads as though it also covers "Who qualifies for a second monitor?" Scope the lookup to one employee's request, identified by request number, so that policy questions stay with knowledge.
The set of available actions affects selection too. Each extra action is another operation the description has to account for. If you find an action that the agent doesn't need while you refine descriptions, remove it in the Inputs panel of the Tool details dialog.
Learn more in Manage and delete tools in an agent.
Shape tool behavior with instructions
Descriptions tell the orchestrator what each tool is for. Your agent's instructions, which you edit on the Build tab, are the primary way to control how the agent behaves. They tell the agent what to do, how to respond, and what to avoid, including which tasks to decline or redirect and how to handle unclear input. For tools, use instructions to say when to use or avoid a tool and how the agent behaves around it.
For the help agent, the submit action changes the list, so you want the agent to confirm details with the employee first. An instruction such as the following one sets that expectation:
When an employee asks to submit a new equipment request, collect the request details, repeat them back, and use the equipment request tool to create the request only after the employee explicitly confirms. Don't submit a request on the employee's behalf without that confirmation. If an employee asks about a request's status without a request number, ask for it. Answer equipment policy questions from knowledge without calling a request tool.
In this design, the confirmation step comes from your instructions. Test that the agent asks for confirmation before it creates an item, and don't assume the behavior until you see it in Preview. A confirmation instruction doesn't grant permission to read someone else's item; enforce that boundary through the connection's access to the list.
Instructions and descriptions guide the orchestrator's choice among tools the agent already has. They don't create a connection, grant access to the list, or guarantee that the orchestrator calls a particular tool. If the tool isn't added, or its connection fails, no change to the wording fixes the problem. Treat it as a configuration issue: confirm that the tool is added, and check that its credentials are current and that the service is available.
Learn more in Configure agent details and instructions.
Verify selection after each change
Clear names, descriptions, and instructions improve how the orchestrator routes requests, but they don't guarantee a particular choice. After you change any of them, test the agent in the Preview tab with a few requests that each have an expected outcome:
- "What's the status of request 1042?" calls the tool's status lookup.
- "I need a new laptop dock" leads the agent to collect and confirm the details before it calls the tool to create the request.
- "Who qualifies for a second monitor?" gets an answer from the policy knowledge, with no tool call.
The submit action creates an item that stays in the list after the conversation ends, so use test data while you build.
You don't need to restart the conversation after every edit. When you edit your agent on the Build tab during an active Preview conversation, the turn in progress continues to use the previous configuration, and the next turn picks up your changes automatically. Make one small change, send a follow-up message, and compare the result with the previous turn. If a change doesn't take effect after a couple of turns, select New chat to start a new conversation.
When the agent's behavior doesn't match the expected outcome, the symptom points to where you look first.
| What you observe | What to check |
|---|---|
| The agent doesn't call the tool for a request that needs it | Whether the tool's description clearly describes when to use the tool |
| The agent calls the tool, but the result is wrong | The tool's configuration, including parameters or selected actions |
| The tool reports a connection error | Whether the authentication credentials are current and the service is available |
Learn more in Test an agent.
Reflect: Pick one tool in an agent you're planning or building, and rewrite its description to state when to use it, what it needs, what it returns, and what it doesn't do. Which request would you send in Preview to check that the new wording changes the agent's choice?
Later in this module, you explore how to read the activity trace to confirm which tool ran with which inputs and result, and how to identify which test requests to keep for repeatable evaluation.