Write descriptions that help the agent choose
When a request arrives, the agent chooses among its capabilities based partly on how you describe them. This unit covers how the agent makes that choice and how you guide and test it.
How the agent chooses
After you add knowledge, tools, skills, and connected agents to an agent built on the GitHub Copilot harness, the agent decides for itself which one to use for each request. You don't script those choices step by step. Instead, the agent's choice draws on:
- The name and description of each tool, skill, and connected agent.
- The user's message and the conversation so far.
- The agent's instructions.
You write most of these names and descriptions, so along with the instructions, they're a direct way to steer the agent's choices. When descriptions are vague or overlap, the agent is more likely to choose the wrong capability.
The number of capabilities matters too: a small set of clearly described capabilities is easier for the agent to choose from than a large, overlapping one. Remove any capability the agent doesn't need, such as an MCP server you no longer use, or turn off individual MCP tools that don't belong.
Write tool descriptions that say what and when
A good tool description tells the agent when to use the tool and what it returns. Start with a specific name, such as "Get case status" instead of "Case tool," and avoid descriptions that overlap with other tools.
For example, compare these descriptions for two case tools. Use the same criteria whether you write a description yourself or review one that an MCP server's author wrote:
| Tool | Vague description | Clear description |
|---|---|---|
| Get case status | "Works with cases." | "Retrieve the current status and owner of a case by case ID. Use for status or ownership questions. Returns the case ID, status, and owner. Doesn't change the case." |
| Submit case update | "Handles case requests." | "Submit an approved change to a case by case ID. Use only when the requester asks to update a case and approval is recorded. Returns the submission result. Don't use for status questions." |
The clear descriptions say when to use each tool and what it returns, and each one rules out the other tool's job so the two don't overlap. A description guides the agent's choice, but it doesn't control access. The condition "approval is recorded" helps the agent choose correctly, and the tool's permissions and your approval process still decide whether an update can happen.
Who writes a description depends on the type of tool. When you add an MCP server, you write the server's name and description, and the server's author writes the description of each tool it exposes. If a tool's description is unclear, ask the author to improve it before you rely on the tool.
For Foundry IQ, update the tool's name and description after you connect. Describe the content the knowledge base holds and the questions it answers, in as much detail as you can. The agent uses that description to decide when to search the knowledge base. For example, a description for the field operations team's knowledge base might say that it contains repair procedures and that the agent should use it for questions about how to carry out a repair.
Write skill descriptions that say what and when
A skill packages self-contained instructions for a specific kind of task. The agent activates a skill when a user's request matches the skill's description, much as it chooses a tool. Describe what the skill does and when the agent should use it. For example, a review skill might read:
Name:
review-case-updateDescription: Apply the operations review checklist to a proposed case update and produce a structured recommendation that lists any missing approvals. Use when a requester asks whether an update is ready to submit.
Skill names use only lowercase letters, numbers, and hyphens. A skill's instructions can also tell the agent to use a specific tool in a particular way. For example, the review skill's instructions might tell the agent to use the Get case status tool to confirm the case's current owner before it reviews the update.
Describe connected agents by their specialty
When you connect an agent, you add a description of when to use it. As with tools and skills, your agent uses the connected agent's name and description to decide whether to hand off a request. Describe the connected agent by its specialty, such as "Assess exceptions to the case escalation policy," instead of a broad label like "Handles case questions." If you connect several agents, keep their descriptions distinct from each other.
Test with requests that should and shouldn't match
A good description lets you predict which capability handles a request. Test that prediction with a small set of requests, including some that shouldn't select a given capability:
| Sample request | Intended choice | What to check |
|---|---|---|
| "Who owns case 204?" | Get case status | Does the agent retrieve the status and owner without making a change? |
| "Review this proposed update for missing approval." | Review skill | Does the response follow the checklist? |
| "Submit the approved update for case 204." | Submit case update, if approval and access checks hold | Does the agent choose the update tool only under its stated conditions? |
| "What does the escalation policy say?" | Policy knowledge source | Does the agent answer from the policy? |
Send each request on the Preview tab, and then open the activity trace to see which knowledge source, tool, or skill the agent used. For a tool, the trace also shows what the agent passed and what the tool returned. A correct-looking response alone doesn't show which capability produced it. For a connected agent, send one request inside its specialty and one outside it, and confirm that each goes where you expect. When the agent chooses differently than you intended, refine the name, the description, or the agent's instructions. Use the instructions when descriptions alone don't tell the agent which tool to use, which inputs to provide, or what to check first.
Reflect: Pick two tools or two connected agents that an agent you work on could confuse. What would you add to each description so the agent can tell them apart?