get_top_topics

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

With no annotations provided, the description carries the full burden and adds valuable behavioral context: it discloses that results are sorted by engagement score, includes pagination details (0-indexed, page=1 for more topics), and specifies default values (e.g., 'monthly' as default period). However, it doesn't mention rate limits, authentication needs, or error handling, leaving some gaps.

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-structured and front-loaded with the core purpose, followed by parameter details, usage guidelines, and examples. Every sentence adds value—no wasted words—and it efficiently communicates necessary information in a compact format.

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?

Given the tool's moderate complexity (2 parameters, 100% schema coverage, output schema exists), the description is complete: it covers purpose, parameters with examples, usage scenarios, return behavior (TopicSummary objects sorted by engagement), and distinguishes from siblings. The presence of an output schema means return values don't need explanation, and all gaps are adequately filled.

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 meaningful semantics beyond the schema: it explains the purpose of each period option (e.g., 'daily' for today's trends, 'yearly' for impactful discussions) and clarifies pagination usage ('Use page=1 to get more topics'), enhancing understanding without redundancy.

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 clearly states the specific action ('fetch top-performing topics') and resource ('topics'), distinguishing it from siblings like 'get_hot_topics' or 'get_new_topics' by emphasizing ranking based on performance over a time period. The opening sentence directly answers what the tool does with precision.

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?

It explicitly provides usage scenarios ('Find the most valuable discussions', 'Research historically important threads', 'Identify evergreen popular content') and examples ('Use "yearly" to find the most impactful discussions, or "daily" to see what's trending today'), giving clear context for when to apply this tool versus alternatives like 'get_hot_topics' for trending content without performance ranking.

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