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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the basic mutation profile is covered. The description adds valuable non-schema context: the exact-quote requirement and the warning that it 'never accepts a guessed amount', which guards against amount fabrication and goes beyond what the annotations say.

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 sentences, purpose front-loaded in the first clause, followed by the sequencing and safety constraints. Minor redundancy between 'only with the exact returned quote' and 'never accepts a guessed amount', but generally tight.

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?

An output schema and annotations are present, so return-format and safety details need not be re-explained. However, for a destructive payment mutation in a crowded payment/verification sibling set, the description should clarify how it differs from privatepay_settle, privatepay_job_payment, and verify_receipt; that gap leaves the agent to infer routing.

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 50%: signature is described in the schema, but job_id has only a name and pattern regex. The description adds no meaning to job_id (e.g. that it must be the job from the prior call) and references 'the exact returned quote' even though no quote parameter exists, which could mislead about the actual inputs.

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 verb 'Confirm' plus resource 'an authorized payment reference for a selected request' is specific, and the description notes it returns the payment/execution result. It names create_paid_job as its predecessor, which helps orient the agent, but it does not differentiate itself from lookalike payment siblings such as privatepay_job_payment, privatepay_settle, or verify_receipt.

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?

Explicit sequencing ('Use this after create_paid_job') and a hard precondition ('only with the exact returned quote') give the agent clear when-to-use context. It stops short of stating when-not to use it or naming the closest alternative payment tools.

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