catalog_releases

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

No annotations exist, so the description bears full burden. It discloses the tool's core behavior (lists available versions and recommended version), the accepted version spec syntax, and the purpose of checking availability before doc_extract. It does not explicitly state read-only nature, but the verb '查看' (view) implies a non-mutating operation, and the description adds meaningful context beyond the simple name.

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?

Three logically ordered sentences: what it does, accepted version spec formats, and when to use it relative to doc_extract. Every sentence is meaningful and no filler or redundancy exists.

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 single-parameter, read-like tool with no output schema, the description covers the core purpose, accepted input formats, and a critical usage ordering hint. It does not describe the return structure in detail, but the phrase '可用版本清单与推荐版本' gives a reasonable expectation. Overall sufficient for an agent to select and invoke 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?

Schema coverage is 100%: the only parameter id is fully described in the schema as '条目规范 id（catalog_lookup 返回）' (canonical id from catalog_lookup). The description does not add further detail about the id parameter itself, only about the tool's overall behavior, so baseline 3 applies.

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?

Description provides a specific action (view/list) and resource (available versions and recommended version for an entry). It clearly differentiates from sibling tools: catalog_lookup likely finds entries and doc_extract extracts docs, while this lists versions. The verb and object are unambiguous.

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?

Explicitly states when to use this tool ('先于 doc_extract 调用' — call before doc_extract) to verify target version availability, and also explains supported version formats (latest, exact, prefix). This gives clear context for invocation relative to a sibling tool.

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