Recommendations for agent descriptions
Agent descriptions help the AI system determine what each agent is designed to do and when to use it. They guide the system in interpreting user intent and selecting the most appropriate agent for the task, which improves routing accuracy and overall performance.
A strong description also sets clear expectations for users and helps prevent misrouting or task failure. It supports consistency across workflows especially when multiple agents are involved and contributes to a more reliable and scalable experience.
Before you begin
Consider the following facts when you plan to build an agent and writing its description:
- Descriptions guide the system in matching user intent to the correct agent.
- Poorly written descriptions can lead to misrouting or task failure.
- Descriptions must reflect the agent’s purpose, capabilities, and limitations.
- All agent components, such as tools, instructions, and knowledge, benefit from clear, well-structured descriptions.
Descriptions must also define how the agent collaborates with other agents by specifying its role, the criteria for routing tasks to it, and the contextual understanding it uses to make intelligent decisions. These elements are essential not only for routing accuracy but also for enabling agents to work together effectively in multi-agent workflows. Including this information directly in the description eliminates the need for a separate procedure page. Since the routing logic and delegation rules are embedded in the agent’s identity, it makes the system more scalable and easier to maintain.
Using context in agent descriptions
Descriptions can include contextual cues that help the system make intelligent decisions. For example:
- Specify when the agent is used based on task type or user profile.
- Mention dependencies on other agents or tools.
- Use consistent terminology across related agents to support better categorization.
Context also includes domain expertise. Clearly stating what the agent specializes in, such as HR, IT support, or finance, helps the system categorize it correctly and match it with relevant queries. Using domain-specific keywords reinforces this categorization and improves routing precision.
Recommendations for writing effective descriptions
Use the following examples to help write agent descriptions that support clarity, accurate query matching, and helpful responses.
What to do
| Category | Recommended instruction |
|---|---|
| Be specific | "Handles HR tasks like onboarding, vacation tracking, and policy lookup." |
| "Specializes in IT support for software installation and troubleshooting." | |
| Focus on purpose and scope | "Designed for finance-related queries such as expense reporting and budget tracking." |
| Define boundaries | "Not intended for legal or compliance advice." |
What to avoid
| Category | Recommended instruction |
|---|---|
| Don’t be vague | "Helps users with tasks." |
| "Supports general inquiries." | |
| Don’t use unsupported logic | "Responds differently based on user emotion." |
| Don’t include conflicting roles | "Handles all HR and IT tasks." |
Descriptions must also highlight the agent’s strengths and limitations. It helps the system determine whether the agent is the best fit for a task and prevents misrouting. It also sets realistic expectations for users. Avoiding overly technical language helps ensure that the system can parse the description reliably and that users understand what the agent can and cannot do.
Agent description example
The following example shows how to clearly define an agent’s purpose, capabilities, and limitations in a way that supports accurate routing and user expectations.
Employee Support is an agent that assists with Human Resources (HR) tasks across the employee lifecycle. It handles onboarding, offboarding, and general HR inquiries. The agent can populate HR systems, trigger workflows, validate local holidays, and generate vacation reports. It does not provide legal advice and is not designed for candidate sourcing or screening.
What to do next
After you write the description, follow these steps:
- Test the agent with varied user inputs to validate routing behavior.
- Review how the system interprets the description and adjust if needed.
- Update the description regularly to reflect changes in agent capabilities or scope.