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

With no annotations provided, the description carries the full behavioral burden and does substantial work: it discloses that the operation is mutating, what gets restored, that snapshots are kept for the last 10 mutating saves, and that unknown recordings/versions return not-found. It stops short of explicitly stating whether the revert itself creates a new snapshot or whether the pre-revert state remains recoverable, but the snapshot policy implies recoverability.

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 dense sentences, each adding distinct value: the core operation, the snapshot retention policy, and ownership/error behavior. The main action is front-loaded and there is no filler.

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 two-parameter mutating tool with no output schema and no annotations, the description covers the operation, restoration scope, retention, authentication, and error behavior. The main residual gap is ambiguity about whether the revert creates a new snapshot and whether the prior state is recoverable, which is minor but prevents a perfect score.

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 of 3 applies. The schema already describes recordingId and version clearly, and the description adds useful context about the last 10 versions and authentication, but it does not add significant meaning beyond the schema for either parameter.

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 names a specific verb and resource: reverting a test recording to a stored version snapshot, and explicitly states what is restored (steps and meta). It does not explicitly contrast itself with sibling flow_recording_* tools, but 'revert' and 'restored from version' make the operation distinct enough from save/get/delete-step operations.

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 guidance is given about when to choose this tool over alternatives such as flow_recording_save or flow_recording_delete_step. The description covers mechanics, retention, ownership, and error behavior, but it never states the decision context or when not to use it.

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