Optimizing Descriptions

How to write descriptions that help agents discover and use your tracks effectively.

Why descriptions matter

During the discovery phase, agents only load the name and description of each track. The description is the only information the agent uses to decide whether to activate a track. A poor description means the track won't be used when it should be, or will be activated inappropriately.

Anatomy of a good description

A effective description answers three questions:

1. What does this track do?
2. When should it be used?
3. What is the expected output?

Examples

Track	Weak Description	Strong Description
Security Review	"Reviews code"	"Analyze code changes for security vulnerabilities including injection attacks, authentication bypasses, and data exposure. Produces a prioritized list of findings with severity levels."
API Design	"Helps with APIs"	"Review REST API endpoints for consistency, proper error handling, pagination, and adherence to OpenAPI best practices. Generates a report with suggestions."
Migration	"Database migration"	"Generate database migration scripts from schema changes. Supports PostgreSQL, MySQL, and SQLite. Outputs SQL files with up and down migrations."

Recommended length

Aim for 50-200 characters. Short enough to scan quickly, long enough to be specific.