Mock: complete payment

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

Annotations only supply readOnlyHint=false, so the description usefully adds that this is simulation-only and that it returns a signed callback payload plus the updated payment — context an agent cannot get from the schema. It omits whether mock mode must be enabled, whether the order must already exist, and any side effects on the stored 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?

Two sentences with zero filler, and the most important constraint ('MOCK MODE ONLY') is front-loaded. Every clause carries new information: mode, action, return payload, and the required follow-up tool.

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 necessary work of describing the return value (signed callback payload + updated payment), which is exactly what an agent needs to chain calls. The remaining gap is parameter-level behavior, especially how 'outcome' alters the result.

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% (provider and order_ref are described, outcome and method are not), so the description needs to compensate — but it mentions no parameter at all. In particular the critical 'outcome' switch (success/failure) that determines the simulated result is left entirely undocumented, and the optional 'method' field is unexplained.

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 ('Simulate the customer finishing checkout') on a specific resource, and the 'MOCK MODE ONLY' prefix immediately separates it from the real payment siblings like payments_create_payment. It also names the downstream sibling payments_verify_payment, so an agent can place the tool in a workflow without opening any schema.

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?

'MOCK MODE ONLY' is an explicit usage constraint, and 'feed it to payments_verify_payment' tells the agent the required next step. It stops short of saying when to pick this over payments_simulate_webhook or that a payment must exist first, so there is no full when/when-not routing.

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