buy_full_report

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

With no annotations, the description carries the full burden and does well: it discloses that money changes hands ($49), that the call is asynchronous (approve_url → buyer approves in PayPal → report link appears at status_url), and that consent has legal consequences under Austrian FAGG. It omits whether repeat calls create duplicate orders, idempotency, and behavior on invalid or foreign scan_ids.

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?

Front-loaded with the action and price, then the return shape, then the consent constraint, then per-argument notes — a sensible order. The Args block is largely non-redundant, though the repeated 'must be true' phrasing and the legal parenthetical add a little bulk.

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 exists, and the description compensates by naming approve_url, status_url, and the eventual report link, plus the approve-then-poll flow. Missing only failure modes (invalid scan_id, unpaid approval timeout) for a payment tool, which is a modest gap rather than a blocker.

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 0%, so the description must compensate, and it does: scan_id's provenance is named (from scan_tls_raw), and consent_immediate_delivery's meaning, required value, and legal semantics are explained rather than restated. Both parameters gain meaning that the bare boolean/string schema cannot convey.

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 and resource ('Buy the full post-quantum readiness report'), adds price ($49) and a precondition ('for a prior scan'), which cleanly separates it from the scan_tls / scan_tls_raw / start_monitoring siblings. An agent can tell this is the monetization step, not another scan.

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?

Explicitly ties the input to a sibling ('the scan_id returned by scan_tls_raw') and spells out the exact precondition for consent_immediate_delivery. It lacks a when-not clause (e.g., what to do if the buyer declines consent, or whether a purchase already exists for that scan), so it is clear but not fully routable.

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