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

Adds value beyond annotations: clarifies it creates exactly one pending invoice, does not pay it, and never treats a redirect as settlement. These are meaningful behavioral caveats beyond readOnlyHint/destructiveHint/openWorldHint. Missing detail on reversal/irreversibility but otherwise solid.

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?

Two tight sentences, front-loaded with the precondition and the core action, no filler. Every clause carries meaning.

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?

No output schema, no annotations covering mutation semantics beyond the hints, and half the parameters undocumented. Description covers the safety pattern well but leaves the operation_id linkage and return behavior unclear, which matters for a mutation tool.

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 coverage is only 50% (operation_id has no description). The description references 'the prepared authorization' and 'exactly one' invoice, vaguely implying operation_id's role, but doesn't explain that operation_id ties to a prior prepare call or that confirm_invoice_creation must also be true. Fails to compensate for the coverage gap.

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?

Specific verb (create) and resource (pending Grynvault supporter invoice), clearly distinct from prepare_grynvault_supporter_invoice by the verb 'create' vs. 'prepare'. It doesn't explicitly name the prepare sibling, but the create/prepare distinction and the mutating nature are clear.

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?

States the precondition ('After separate explicit user confirmation') and invokes the prepare workflow implicitly ('sign the prepared authorization'). The when-not is partially covered by noting it doesn't pay the invoice, but no alternative tool is named when a caller hasn't prepared yet.

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