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

Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=false and openWorldHint=true, so safety-profile burden is largely covered. The description does add real context beyond that — newer versions are preserved and no code/deployment is affected — but it says nothing about reversibility, auth needs, or the meaning of expected_revision concurrency.

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 tight sentences with the core action front-loaded and the Git-branch disclaimer placed early where it prevents the most likely misread. No filler, though the closing usage sentence is terse enough to be slightly cryptic.

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 destructive, non-idempotent mutation with no output schema and five undocumented required params, the description leaves meaningful gaps. It gestures at the return ('returned branch') which partially offsets the missing output schema, but the concurrency and environment semantics an agent needs to call it correctly are absent.

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% across five required parameters, so the description must compensate but barely does. 'From a prior version' loosely maps to checkpoint_id and 'returned branch' hints at output, but name, environment (staging/production), and especially expected_revision (optimistic-concurrency token) get no explanation.

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+resource ('Create an alternative checkpoint history from a prior version') and explicitly rules out confusion with Git branching ('Does not create a Git branch'), which helps distinguish it from cousins like supabase_create_branch. However, it never differentiates itself from the closest sibling, beon_create_app_checkpoint, so an agent still has to infer the boundary.

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 line 'Use the returned branch explicitly in captures' gives a downstream usage hint, implying this tool is a setup step before capture operations. But there is no when-to-use/when-not guidance relative to beon_create_app_checkpoint or beon_pin_app_checkpoint, so selection among siblings remains implicit.

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