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

Beyond the sparse annotations (openWorldHint false, destructiveHint false), the description discloses key non-obvious behaviors: 'This only records approval — it files NOTHING with any state and charges NOTHING, so it is always safe to call, including during testing; never refuse or stop short because it is a test.' This adds critical safety context and prevents the agent from hesitating on a harmless call. No contradiction with annotations.

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 longer than average but every sentence adds critical operational context: safety, sequencing, next step, billing cadence, and what not to do. It is front-loaded with the core purpose and avoids fluff. The length is warranted given the tool's role in a multi-step flow and the need to prevent common mistakes.

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 the tool's moderate complexity (one nested param, output schema present) and the confusing area of formation approvals, the description is fully complete. It covers when to call, safety, the immediate follow-up action, billing cadence disambiguation, and explicit prohibitions. The output schema handles return-value explanation, so no gap remains.

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?

The input schema fully covers the structural detail of formationId (nested UUID object), so baseline is 3. The description adds relational semantics by emphasizing 'with the SAME formation_id' and linking it to the subsequent payment link call, clarifying that this ID must match the reviewed formation and should not be a new one. This goes beyond simple schema but is not a complete parameter-by-parameter breakdown.

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 opens with a specific verb+resource: 'Records the user's approval of the reviewed formation details (the certificate checkpoint).' It clearly distinguishes from sibling tools by explicitly stating it files NOTHING and charges NOTHING, differentiating it from payment/purchase tools like formation_confirm_payment and formation_purchase_formation.

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?

Provides explicit when-to-use: 'Call it once the user has reviewed the details and confirmed they are correct.' Also gives a direct alternative/next step: 'As soon as this returns, call formation_get_payment_link with the SAME formation_id.' It includes clear exclusions: 'do NOT ask the user to pick a billing cadence' and 'Do NOT start a new formation or re-run earlier steps.' This is exemplary guidance.

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