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

Annotations already declare read-only, idempotent, non-destructive, closed-world, but the description adds real context: the response may contain activation codes, LPA, QR/install links and usage data, and that token/activation data are secrets not to be shared publicly. It also clarifies the semantic limit that the call does not itself confirm payment.

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?

Three front-loaded sentences with the core action first and the secrecy caveat last. Minor redundancy between "treat the token and activation information as secrets" and "do not share the output publicly," which say nearly the same thing.

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 no output schema, the description does the work of sketching the return payload (status, activation code, QR/install links, usage data) and flags the sensitivity of the result. It omits error behavior for an invalid or mismatched token and does not explain how include_usage changes the response.

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%, so the description must carry the load. It explains order_id/order_token provenance and secrecy, but the third parameter include_usage is never mentioned, leaving an agent to guess whether usage data appears only when set.

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 ("Retrieve payment/fulfilment status") scoped to "exactly one order" and names the two identifiers required. This clearly separates it from sibling mutations like prepare_order, purchase, and create_checkout.

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?

Establishes the precondition that order_id and order_token come "from checkout or purchase," which tells the agent this is a post-purchase lookup. It also warns the result "never confirms payment by itself," but never explicitly contrasts with siblings such as prepare_order or get_wallet.

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