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

Annotations already declare readOnlyHint=true and openWorldHint=true, but the description adds valuable behavioral context: the exact limit (20), ordering (newest first), return fields (title, description, date, categories, url), and the implication that it returns snippets (not full articles) by directing to get_doc_page. This goes beyond the annotations without contradicting them.

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 compact and front-loaded: it states the core action first, then usage conditions, then return format, then a negative usage note. Every sentence earns its place, with no redundancy or fluff.

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 zero parameters and no output schema, the description is fully sufficient. It specifies the result set size, ordering, fields returned, how to access full content (via get_doc_page), and when to avoid this tool. An agent has everything needed to decide whether and how to call it correctly.

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?

The tool has zero parameters, so the baseline is 4. The description correctly doesn't attempt to explain parameters since none exist, and it implicitly conveys that no arguments are needed by stating the action without any prerequisites. This is appropriate for a parameterless tool.

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 explicitly states the verb, resource, and limit: 'List the 20 most recent posts from the Capawesome blog, newest first.' It also differentiates from siblings by specifying when to use it (recent releases, announcements, etc.) and when not to (topic questions), making the tool's purpose unmistakable.

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?

Clear guidance on when to use: 'Use this when the question is about what is new...' and explicit exclusion: 'Do not use this to answer a topic question...' It also names the alternative `search_docs` and explains the reason (feed only has newest posts). Additionally, it routes the agent to `get_doc_page` for full articles, covering the full usage path.

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