Recommendations for agent descriptions

Edit online

The agent description is used by an agent to determine when and how to delegate a task to a collaborator agent, tool or knowledge ensuring the right request is sent to the right capability. When adding any artifact (a collaborator agent, tool, or knowledge) to an agent, the agent description is critical to the agent’s success.

Agent descriptions complement the agent names by providing detailed information about their purpose, capabilities, and usage. A well-written description helps users understand the agent’s role and potential applications.

Descriptions must not be written in isolation. They must reflect the agent’s scope, use cases, and interaction with collaborators, tools, and knowledge bases. This ensures reliable routing and prevents ambiguity.

Key concepts

Consider the following facts when you plan to build an agent and writing its description:

  • Descriptions as instructions: Treat the agent description like instructions to the agent on how it should use the artifact (collaborator agent, tool, or knowledge base) in question.
  • Hierarchy matters:
    • Agent descriptions are broader and set the overall purpose.
    • Collaborator descriptions narrow the scope to specific tasks.
    • Tool descriptions are the most specific, clarifying exact functionality.
  • Avoid overlap: Each agent should have a distinct scope. If scopes are similar, clearly differentiate them.
  • Include context markers:
    • Geographic scope (for example, “US”) helps route queries correctly.
    • Domain-specific language (for example, “pet-parents and their fur-babies”) sets tone and aligns with instructions.
  • Don’t overload descriptions: Mention core capabilities, not every tool. The agent should infer tool usage from context.
  • Define trigger conditions: Clarify when the agent must use the artifact, such as “Use this when the user requests supplier risk evaluation or mentions creditworthiness.”
  • Specify actions: Be specific about the actions the artifact should perform. When possible, include how the artifact should perform those actions, such as “Access loan data from loan APIs, calculate affordability, and summarize affordability differences.”
  • Define restrictions: Note desired restrictions and limitations. Most artifacts will have a boundary they should stop at, such as “Do not give legal or tax advice, only provide estimates and data-driven comparisons.”
  • Use appropriate jargon: Define any industry-specific terms or acronyms so they won’t be misunderstood.

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.

Agent description examples

The following examples shows how to clearly define an agent’s purpose, capabilities, and limitations in a way that supports accurate routing and user expectations.

HR agent description

Use this agent to compare employee compensation data across similar roles and regions. Retrieve current market benchmarks from HR databases, analyze differences, and summarize how internal pay aligns with external trends. **Do not provide policy recommendations or make promotion decisions**.

Supplier Analysis tool routing description

Assesses supplier risk by retrieving ratings, credit data, and compliance history from Dun & Bradstreet and internal procurement systems. Summarizes financial stability, delivery reliability, and compliance risk. **Do not make purchase decisions or alter supplier records**.

Finance agent routing description

Analyze portfolio performance by pulling real-time stock and bond data, calculating returns, and comparing results against benchmarks. Summarize key performance drivers and risk factors. Do not provide personalized investment advice or execute trades.

Agent and collaborator description for a pet store

The following example demonstrates how to write clear, context-rich descriptions for an agent and its collaborators, tools, and knowledge bases.

This also shows how tone and language can align with the agent’s persona, which should be reinforced in the instructions for a consistent user experience.

Agent description

USPetTreeAgent: A US PetTree attendant serving the needs of pet-parents and their fur-babies. It can help give general pet care advice, assist in the pet adoption process by matching users to cats and dogs, and order pet supplies from the PetTree US Store.

Collaborator description

MatchMakerAgent: An agent to search the PetTree cat and dog registry to match animal lovers with cats and dogs seeking a forever home, and file a pet adoption application.

Tools for MatchMakerAgent

  • SearchPetTreeCats: Search the PetTree registry for cats available for adoption.
  • SearchPetTreeDogs: Search the PetTree registry for dogs available for adoption.
  • GetPetTreeAnimalProfile: Get the full profile of an individual cat or dog.
  • ViewAnimalPhotos: View pictures of cats and dogs available for adoption.
  • FileAdoptionApplication: File a pet adoption application for a specific cat or dog.

Knowledge base for MatchMakerAgent

  • Cat Breeds Care: Facts, personalities, and care guides for different cat breeds.
  • Dog Breeds Care: Facts, personalities, and care guides for different dog breeds.

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.