Get a revision

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

Annotations already declare readOnlyHint=true, so the description is not required to state safety. It adds value by describing exactly what the snapshot contains ('statement, test cases, solutions and settings as they stood'), which goes beyond the annotation. It does not mention any side effects or error conditions, but given the read-only annotation, the bar is lower and this is acceptable.

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, front-loaded sentence that states the core purpose first, then the addressing modes. It contains no redundant words or filler. Every clause earns its place.

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 an output schema available, the description does not need to explain return values. It covers the purpose and addressing modes succinctly. It could mention that the snapshot is immutable or that revision ids come from repovive_list_revisions, but those are minor gaps. Overall, it provides enough context for an agent to call the tool 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 description coverage is 100%, so baseline is 3. The description adds semantic value by explaining the two addressing modes ('by revision id, or by target plus sequence number'), which clarifies how the four parameters relate. This is beyond the schema's individual parameter descriptions and helps the agent understand the intended usage patterns.

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 action ('Fetch one saved revision') and specifies the resource ('full snapshot — statement, test cases, solutions and settings as they stood'). It also distinguishes from siblings by emphasizing 'one saved revision' and the two addressing modes (revision id or target+sequence), which is specific and not a tautology.

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 provides clear context for when to use the tool: when you need a single revision's full snapshot. It explains how to address the revision (by id or target+sequence number), which guides usage. However, it does not explicitly name alternative tools like repovive_list_revisions or repovive_diff_revisions, so it lacks explicit exclusions or comparisons, but the purpose is sufficiently clear.

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