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

Far exceeds what annotations provide. Annotations declare it is not read-only, idempotent, and non-destructive; the description adds richer traits: it confirms no run, promotes no table, approves no repair, returns immutable coordinates, doesn't go live, and specifies the held/confirmation flow and a failure mode (revision_registered_replay_not_started). This is unusually complete behavioral disclosure with no contradictions.

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 content is front-loaded and dense with essential behavior, but several sentences are lengthy and mix concerns (flow, error handling, UI instructions). It is not bloated with filler, yet the wall-of-text structure reduces scannability for an agent.

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 no output schema and only 2 params (one nested, undocumented), the description compensates by specifying return fields ({recipe_id, recipe_digest, ...}), the held-return variant, and an error path. It covers the full operational lifecycle needed to call and follow up 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 0%, but the description compensates by providing a concrete example payload showing both required params ('recipe': {...whole revision document...}, 'sources_from_run': '...'). It still doesn't fully explain the recipe document structure or clarify that sources_from_run must be a UUID (covered by schema format). Baseline 3 is appropriate given the example adds context but leaves the recipe object under-specified in prose.

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 states a specific verb (registers a proposed revision) and resource, and explicitly distinguishes its behavior from siblings: 'starts EXACTLY ONE run: a replay of the named successful run's retained inputs', 'confirms no run, promotes no table and approves no repair'. An agent can identify it apart from replay_run, start_run, promote_table, and approve_full_run without opening schemas.

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?

It provides clear when-to-use context (propose a revision; then confirm via confirm_run if held; re-propose after fixing preconditions) and names alternatives (confirm_run, approve_full_run, promote_table) it does not perform. No explicit when-not-to-use, but strong operational guidance.

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