Creating knowledge descriptions

Edit online

When you upload documents to your agent’s knowledge base, include a clear and informative description. It helps the agent understand and interpret the data. The agent then decides whether to use the knowledge in its responses or rely on another method, such as calling a tool or by using the large language model (LLM).

Well-written descriptions improve:

  • Response relevance

  • Retrieval accuracy

  • User experience

Writing effective descriptions

Use the following recommendations to help write clear, purposeful knowledge descriptions that improve agent understanding, response relevance, and user experience.

Supports What to do

Does not support What to avoid

Use clear, concise language that reflects the document’s purpose.

To write vague or generic descriptions like "general info" or "misc".

Highlight key topics or actions that the document supports.

To include irrelevant details or overly technical jargon.

Focus on how the content helps the agent respond to user queries.

To copy the document title without adding context.

Mention specific use cases or scenarios the document covers.

To leave the description field blank or incomplete.

Use consistent formatting and tone across all descriptions.

Mixing styles or by using inconsistent terminology.

Example of an effective description

The following example shows a knowledge description for HR policies:

_"This knowledge base includes HR policies, employee handbooks, and guidelines on benefits, leave, and performance management. It supports queries like 'What is the parental leave policy?' and 'How do I apply for remote work?' Keywords: leave policy, remote work, benefits, performance review, onboarding."_

What to do next

  • Add or update the description for each knowledge file during upload or editing.

  • Test the agent to confirm that it uses the knowledge appropriately in responses. For more information, see Evaluating a draft agent.

  • Refine knowledge behavior, if needed. For more information, see Customizing knowledge settings.