Describing an agent

After an agent is published, its developer describes it in plain language. Search matches user queries against that description. An agent without a description cannot be found by search.

Writing a good description

Write for the person who will type the query, not for the system. A good description says what the agent does for the user: the questions it answers, the actions it takes, and what it does not do. Two to five sentences is typical. The limit is 5,000 characters.

This agent answers employee and contractor questions about workforce policies
and personal entitlements. It covers vacation and leave policies, benefits
eligibility, onboarding and offboarding, workplace conduct guidelines and
general HR procedures. It can look up the requester's own HR records where
permitted, such as accrued vacation balance. It cannot make policy exceptions,
approve requests or modify HR records.

A description that only names the mechanism, such as calls the HR API and summarizes the JSON, matches poorly, because users do not ask about mechanisms. Every submitted description is checked for this. A description that does not say what the agent provides to the user comes back with an explanation of what to change.

Languages

Descriptions and queries may be in any major language, and they do not need to be in the same one.

Submitting a description

The description is submitted from the agent's page, after the agent is published. Indexing takes 15 to 30 seconds, and the agent is searchable as soon as it completes. If indexing fails, the reason is shown and the audit log keeps the record. A new description replaces the old index entry. Removing the description takes the agent out of search without deleting the agent.

Overlapping agents

When two agents cover overlapping ground, a query in that territory returns both. With the default search behavior the higher-ranked agent runs; with a behavior that offers choices, the user chooses. The overlap may be intended. If it is accidental, sharpen the descriptions: say what each agent is for and what each leaves to the other.