Verify payment callback

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

Annotations already mark it read-only, but the description adds behavior the annotations cannot convey: the outcome semantics (valid vs paid) that drive downstream fulfillment, and the fact that for gateways that do not sign callbacks it resolves verification through the status API — i.e. an outbound network call, not a purely local computation. Those are exactly the traits an agent needs to interpret the result correctly.

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?

Four short sentences, front-loaded with what is being verified, then the fulfilment rule, then the valid/paid distinction, then the unsigned-gateway fallback. No filler and no repetition of schema or annotation content.

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?

Covers the hard parts of a nested-payload verification tool with no output schema: it explains what the two key result flags mean, which is the main ambiguity. It leaves gaps around amount-mismatch handling and what the response contains beyond valid/paid, but the critical decision logic is present.

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 100%, so provider, payload, order_ref, expected_amount and include_raw are all documented in the schema itself. The description adds nothing about the two highest-risk parameters — order_ref as an anti-replay binding and expected_amount in paise — so the baseline 3 applies.

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 (verify) and resource (the checkout callback payload) and scopes it to what the browser/app received, which implicitly but clearly separates it from payments_verify_webhook (server-side webhook). The parenthetical examples (Razorpay handler response, PayU/CCAvenue/Paytm POST-back) make the target artifact unmistakable.

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?

Gives a concrete decision rule with a hard constraint: fulfill ONLY when paid=true, and warns that valid=true is not a fulfilment signal because a genuine failure is still valid. That is strong when-to-act guidance. It does not name sibling tools (e.g. verify_webhook vs this one) or state what to do on an invalid callback, so it stops short of full alternative routing.

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