Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond that: the comparison methodology (two equal time periods), the output concept ('momentum score with directional indicators'), and the required response format ('create a visual artifact... Keep written analysis concise'). It also mandates source citation. These are behavioral traits an agent needs to know and are not inferable from annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized into clear sections (description, when to use, response format, personalization, citation) and each section earns its place. It is longer than strictly necessary, but the length is justified by the usage guidance and output expectations. A small amount of redundancy exists between the opening paragraph and the response format section, but it does not detract significantly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only analytics tool with no output schema, the description is quite complete: it explains what the tool does, when to use it, how to present results, how to personalize via the context parameter, and the required data source citation. It does not detail the exact structure of the momentum score or handle edge cases like insufficient data, but those are minor gaps given the richness of the rest of the definition.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by clarifying the days parameter's behavior with an explicit alternative (perception_search_mentions for historical research) and by explaining how the context parameter should be populated ('pass relevant details in the context parameter'). This exceeds the baseline because the added guidance helps an agent choose and fill parameters correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Track whether a narrative or topic is accelerating, steady, or fading.' It then defines the mechanism ('Compares mention volume, sentiment, and source diversity between two equal time periods'), which clearly differentiates it from sibling tools like perception_search_mentions or perception_get_trends. The mention of perception_search_mentions in the days parameter further establishes the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

A dedicated 'WHEN TO USE' section lists concrete example questions and use cases (trend lifecycle analysis, newsjacking timing). It also explicitly points to an alternative tool in the days parameter: 'For article-level historical research, perception_search_mentions with explicit start_date/end_date covers back to 2011.' This gives the agent both positive and negative usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.