Compare 2ools versions

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

The annotations explicitly mark the tool as readOnlyHint: true, idempotentHint: true, destructiveHint: false, which already declare it as a safe, read-only, idempotent operation. The description does not contradict these and adds useful context: it reports lineage, review state, page diffs, byte sizes, and SHA-256, which helps the agent understand the behavior's scope. However, it does not mention rate limits, pagination, or performance for large comparisons, so it falls short of perfect transparency.

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 a single, dense sentence that front-loads the core purpose ('Compare two saved versions in one project without returning source') and then lists all reported attributes. Every word carries information. No fluff. This is an example of excellent conciseness.

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 has 3 well-documented parameters, no output schema, and rich annotations (readOnly, idempotent, non-destructive), the description covers what the tool does and what it reports. The agent can infer it returns a comparison summary. However, it could be slightly more complete by hinting at the exact output format (e.g., 'returns a diff object with ...') since there is no output schema. Still, for a comparison tool with good structured data, this is quite complete.

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 input schema has 100% coverage with descriptions for project_id, left_version_id, and right_version_id. The schema already provides UUID format and a note that left is 'Earlier or baseline' and right is 'Later or candidate'. The description adds value by indicating the comparison is within one project and clarifies the output fields. Since all parameters are well-documented in the schema, the description provides a meaningful but not essential supplement, earning a 4.

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 tool compares two saved versions in one project, specifies what it reports (lineage, review state, page additions/removals, byte sizes, SHA-256), and distinguishes itself by noting it does not return source. This is a specific verb+resource and differentiates from sibling tools like approve_version, list_artifacts, etc., though it could be sharper about excluding version export or diff tools.

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 implies this is for comparing saved versions without source, but does not explicitly state when to use this over alternatives like get_version or prepare_version_export. There is no mention of prerequisites (e.g., version IDs must exist), nor is there discussion of when not to use it. With 53 sibling tools including several version-related ones, explicit guidance would improve this dimension.

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