Metadata and descriptions

Good descriptions and metadata make agents easier to find, help language models pick the right tool, and let policies check your configuration. This page explains which fields matter and what to put into them.

Overview

Where	Field	Used by	Purpose
Every component	name, description	People	Find and understand components in the registry
Agent	config.description	Language model	Decide when to hand over to this agent in a team
Agent	config.system_message	Language model	Instructions for the agent
Tool	config.description and parameter descriptions	Language model	Decide when and how to call the tool
Every component	meta_data	Policies, chat interfaces	Describe properties for policy checks and display
Datasource	description	People	Explain what the datasource contains
Document	metadata	Search, citations	Filter search results and show sources. See Ingestion best practices.

Descriptions for language models

Language models decide based on descriptions which tool to call and which agent to hand over to. A vague description leads to wrong or missing tool calls.

Tools

• Say what the tool does, when to use it and when not to.
• Describe every parameter, including format and units, for example “date in ISO 8601” or “temperature in °C”.
• Mention what the tool returns.
• Use enum for parameters with a fixed set of values.

Weak	Strong
Gets downtime.	Returns the downtime events of one production line for a time range. Use it when the user asks why or how long a line stopped. Do not use it for planned maintenance.

Agents in teams

• Describe the agent’s area of responsibility in one or two sentences.
• Make responsibilities of agents in the same team clearly distinct.

Instructions (system_message)

• State the role, the audience and the expected answer style.
• List the tools and when to use them.
• Say what the agent must not do, for example give advice outside its domain.
• Keep instructions for stage-specific values, such as URLs, out of the text. Use environment variables.

Component metadata (meta_data)

Every component has an optional meta_data object. It serves two purposes.

Policy attributes

Top-level keys describe properties that policies check. The service combines them across an agent and everything it uses.

{
  "meta_data": {
    "data_classification": ["internal"],
    "external_communication": true,
    "data_region": "${DATA_REGION}",
    "owner": "maintenance-team"
  }
}

Recommendations:

• Agree on a vocabulary for your tenant: which keys exist, which values are allowed and what they mean. Document it next to your policies.
• Describe facts, not intentions. external_communication: true for a tool that sends emails, even if it is only used internally.
• Put properties where they originate. A tool that reads confidential data gets data_classification: ["confidential"]. The agent inherits it when it uses the tool.
• Use lists for sets of values, such as classifications or capabilities. Lists are combined across components.
• Use placeholders like ${DATA_REGION} for values that differ per stage. They are filled in from the deployment’s environments.
• Do not store secrets in metadata.

Useful attributes to start with:

Key	Example values	Typical component
data_classification	["public"], ["internal"], ["confidential"]	Tools, contexts, agents
external_communication	true, false	Tools that send data to other systems
writes_data	true, false	Tools that create or change data
untrusted_contents	true, false	Tools, toolboxes and workbenches that return content from outside your control, such as emails, web pages or uploaded documents
data_region	"eu"	Tools, models
owner	"maintenance-team"	All

Content from untrusted sources can contain hidden instructions that try to take over the agent (prompt injection). Mark such components with untrusted_contents: true. A policy can then, for example, reject agents that combine untrusted content with external_communication or writes_data.

Display information

The key meta contains information for chat interfaces, for example:

{
  "meta_data": {
    "meta": {
      "description": "Helps maintenance staff analyze machine faults",
      "profile_image_url": "https://example.com/agent-icon.png",
      "suggestion_prompts": [
        { "title": ["Analyze a fault", "Root cause"], "content": "Station 12 shows error E23. What should I check?" }
      ],
      "tags": [{ "name": "maintenance" }],
      "capabilities": { "citations": true, "vision": false }
    }
  }
}

Which keys are shown depends on the chat interface. Recommendations:

• Write the description for end users, not for developers.
• Add two to four suggestion prompts that show typical questions.
• Use tags consistently across agents, so users can find related agents.

Datasources and documents

• Give every datasource a description that says what it contains and who it is for.
• Design document metadata per datasource and use it consistently. See Ingestion best practices.
• Add title and url to documents, so that citations can link to the original. See Source metadata.

Checklist

• Every tool has a clear description and described parameters.
• Every agent has instructions that list its tools and limits.
• Components carry the policy attributes your tenant agreed on.
• Agents visible to users have a description and suggestion prompts.
• Datasources and documents have descriptions and source references.