cancel_contract_to_cash_before_invoice

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

Annotations already establish destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds one useful behavioral precondition about invoice-effect custody, but it does not disclose what is destroyed, whether the cancellation is reversible, or what downstream state changes occur. 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 a single sentence with no filler, and the key condition is front-loaded. It is concise, though the terseness contributes to its lack of clarity.

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?

With four required parameters, zero schema description coverage, and a destructive action, the description is far too sparse. The output schema covers return values, but the description still fails to explain parameter semantics, the exact resource being cancelled, or the meaning of the custody condition.

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%, and the description mentions none of the four required parameters (company_ref, project_ref, run_ref, request.reason). It provides no meaning for the refs or the cancellation reason, so an agent cannot construct a valid call from the description alone.

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 uses the verb 'Cancel' but never plainly names what is being cancelled, leaving the resource to be inferred from the tool name as a contract-to-cash run. The phrase 'no invoice effect has authoritative custody' hints at a pre-invoice cancellation state but is jargon-heavy and does not clearly distinguish this tool from other cancel_* siblings.

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 description gives a timing restriction ('only while no invoice effect has authoritative custody') and implies cancellation should not occur after that state. However, it names no alternative tool and does not explain what to do when the precondition is false, so the guidance is partial rather than explicit.

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