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

Annotations already declare read-only/idempotent/closed-world, yet the description still adds real context: results are published-only, newest-first, short cards with no full text, language editions returned as separate tagged results, and a citation policy. The note that the site is a 3D garden rather than a wiki prevents a common mischaracterization of the output.

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?

Front-loaded with the usage trigger, then output shape, then the anti-pattern routing — good ordering. It is a dense single block mixing invocation guidance, return format, citation policy and domain framing, so a little structure is lost, though no sentence is clearly wasted.

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?

With only two optional parameters, full schema coverage, and an output schema carrying return structure, the description covers everything an agent needs: when to call it, what comes back, how languages split, and how to cite results.

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 coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema by explaining that English and Chinese are distinct result sets each tagged with its language — clarifying why the language filter matters rather than just what values it accepts. It does not mention the limit parameter or default behavior, so not a 5.

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?

Names a specific verb and resource (list recent/published notes) and explicitly contrasts itself with search_articles, so an agent can pick between them without opening either schema. The sibling get_article/list_topics distinction is implied by 'browse without a specific subject'.

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?

Gives the triggering user intent ('latest, newest or recent notes', 'browse without a specific subject') and an explicit exclusion with the correct alternative ('Do not use it to find notes on a specific subject; use search_articles'). This is the when/when-not/alternative pattern at full strength.

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