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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the meaningful detail that revisions come from both editor and agent saves, but says nothing about retention, ordering, pagination, or result size.

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?

One tight sentence with the distinguishing qualifier front-loaded and no padding. It is efficient, though the brevity leaves real gaps unaddressed rather than being optimally sized for a tool with a documented sibling.

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 simple read-only list tool with one parameter and no output schema, the description covers the essentials of what is listed. It falls short on the relationship to restore_map_revision and on the undocumented mapId, so an agent has enough to call it but not full confidence.

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 0%: mapId has no description in the schema, and the description never mentions it, so nothing clarifies whether it accepts a map name, slug, or id, or what happens with an unknown id. For a tool with a required parameter and zero schema documentation, the description should compensate and does not.

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?

States a specific verb (List) and resource (map revisions), plus a useful scope qualifier: 'recoverable' revisions originating from 'editor and agent saves'. This separates it from get_map_draft and get_map by implying historical/restorable versions, though it never names the restore counterpart explicitly.

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?

No statement of when to list revisions versus fetching the live map (get_map) or draft (get_map_draft), and the obvious downstream sibling restore_map_revision is not referenced. The word 'recoverable' faintly implies the recovery workflow, but no condition or alternative is given.

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