compare_versions

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

No annotations are provided, so the description must carry the full burden. It transparently discloses that uncached versions trigger a download that may require a second call. It also explains the two output modes. While it doesn't cover all potential edge cases (e.g., error handling), the key behavioral trait is well documented.

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 concise: four sentences covering two distinct modes, prerequisites, and first-use behavior. No redundant words. Information is front-loaded with the core purpose.

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 9 parameters and no output schema, the description is remarkably complete. It explains the two output modes, how to pick versions, and the caching behavior. The only minor gap is that it doesn't describe the format of the structural summary, but that's a niche detail. Overall, it provides sufficient context for correct tool invocation.

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. However, the description adds significant context beyond the schema: it explains how 'section_number' changes the output type (summary vs. diff), and gives concrete examples like '5.15.2'. The 'old_version' description also clarifies it accepts archive tokens and release selectors, which is not in the schema. This adds substantial semantic value.

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 starts with 'Compare two versions of a 3GPP specification', clearly defining the verb and resource. It then distinguishes two modes: without section_number (structural summary) and with section_number (line-level diff). This differentiates it from sibling tools like 'get_section' or 'list_versions'.

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?

The description explicitly tells when to use each mode and directs to use 'list_versions first to see which versions exist'. It also explains behavior on first use (download/conversion) and instructs to retry if a download is in progress. This is clear guidance on usage vs. alternatives.

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