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

Annotations already flag destructiveHint and openWorldHint, so the safety bar is partially covered, but the description adds genuinely new behavioral context: immediate vs end-of-cycle cancellation and a mandatory human-approval + confirm=true gate for live mode. It does not state whether an immediate cancel is irreversible or what happens on a failed/unknown subscription id.

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, zero waste, with the action and timing front-loaded and the safety gate second. Nothing to trim.

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?

For a destructive mutation with no output schema, the description covers the critical decision points (timing, live-mode confirmation, human approval). Return-value behavior after success and failure modes are left unstated, which is the only real gap.

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 only 25%, so the description must carry the load. It does explain confirm (required true in live mode) and at_cycle_end (now vs cycle end), but adds nothing about provider beyond the enum's 'Gateway id' and nothing about provider_subscription_id format or where to obtain it.

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+resource ('Cancel a subscription') plus the scope choice ('now or at cycle end'), which cleanly separates it from the sibling payments_create_subscription. No sibling is named explicitly, so it lands at 4 rather than 5.

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 prerequisite: live mode requires confirm=true after human approval, and clarifies the two timing modes. It stops short of naming alternatives or when-not-to-use conditions (e.g. use payments_get_status first to verify the subscription exists).

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

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

Annotations already declare readOnlyHint=true, so safety is partly covered, but the description adds genuinely useful behavioral context beyond that: it discloses exactly what is reported (mode and per-gateway env var presence) and guarantees that secret values are never returned. It stops short of describing output shape or what happens if a gateway is misconfigured.

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?

A single compact sentence that front-loads the core behavior and ends with the most important safety guarantee. The 'Doctor:' label is slightly jargony but functions as a fast cue rather than waste.

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?

For a one-parameter, read-only diagnostic with no output schema, the description covers what it reads, what it reports, per-gateway scoping, and a secrecy guarantee. Nothing material is missing for an agent to invoke it correctly.

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% and the single 'provider' parameter has an enum of gateway ids documented as 'Gateway id'. The phrase 'per gateway' weakly implies that the parameter scopes the check to one gateway, but it never states what happens when the optional parameter is omitted (presumably all gateways), which is the one piece of semantics the 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?

The description names a concrete diagnostic operation (reporting mode plus present/missing environment variables per gateway), which is clearly distinct from the transactional siblings like payments_create_payment or payments_refund. It does not explicitly contrast itself with the nearest informational sibling, payments_list_providers, but the resource is unambiguous.

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?

The 'Doctor:' framing implies the tool is for diagnosing configuration problems, which gives an implicit usage context. However, there is no explicit when-to-use guidance, no mention of when to prefer payments_list_providers or payments_get_capabilities instead, and no note about when to pass a provider versus omitting it.

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

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

Annotations only declare openWorldHint=true, so the description carries nearly the full burden. It doesn't say whether the call is idempotent, what happens on duplicate email, whether an error is returned for unsupported providers (payu, cashfree, etc.), or whether auth/credentials per gateway are required — all material for an external write.

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?

A single front-loaded sentence with no filler; the supported-gateway qualifier is placed immediately after the action. It is arguably too terse for the information load, but that is an omission issue rather than verbosity.

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 5 parameters, a nested metadata object, no output schema, and no documented return value (e.g., customer id needed for later payments/subscriptions), the description is too thin. An agent cannot tell what it gets back or how to use the result in follow-on calls.

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 only 20% (only 'provider' is documented), so the description must compensate and does not: name, email, phone, and the nested metadata map are entirely unannotated in both places. The one added value is clarifying which provider values actually support customer creation, which partially offsets the gap but leaves four parameters 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?

Specific verb + resource ('Create a customer record') and it adds a genuinely distinguishing qualifier: only gateways that support customers (Razorpay, Stripe) are viable. This differentiates it from sibling write tools like payments_create_payment or payments_create_subscription, though it doesn't explicitly contrast with them.

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?

The parenthetical implies when the tool is usable (only on Razorpay/Stripe), which is useful, but there is no explicit when-to-use vs. alternatives guidance and no statement of what happens if an unsupported provider from the 8-value enum is passed. Usage is inferable rather than stated.

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

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

Annotations already declare openWorldHint, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond that: the four concrete frontend handling modes for `checkout` (js_sdk, redirect, form_post, manual) and the obligation to persist orderRef + providerOrderId. It stops short of covering failure modes or how provider errors surface.

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 short sentences, zero filler, front-loaded with the verb+resource and then the return-shape enumeration. Every clause carries actionable information.

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 12 parameters, a nested customer object, an open provider enum, and no output schema, the description does the essential work of explaining the response envelope (`checkout` modes), which is the non-obvious part. Remaining gaps — error behavior, provider-specific requirements beyond the schema's return_url note — are minor because the schema is fairly rich.

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 75% and the schema itself documents amount units, order_ref pattern, notify_url/return_url semantics, and idempotency_key default. The description mentions only `checkout` and providerOrderId persistence and adds no meaning to `provider_options`, `include_raw`, or `metadata` beyond what the schema states, 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 and resource ('Create an order / payment session') and immediately clarifies the return contract via the `checkout` discriminator. The action is unambiguously distinct from the sibling set (verify, refund, get_status, cancel_subscription), so an agent can route here without opening the 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?

The description implies the initiation context and gives an operational instruction ('Persist orderRef + providerOrderId'), but never states when to prefer this over `payments_recommend_gateway` (gateway selection), `payments_mock_complete_payment` (testing), or `payments_create_subscription` (recurring). Usage is implied rather than prescribed.

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

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

Annotations only carry openWorldHint=true, so the description does real work by disclosing the two-step nature of the flow — a checkout action is returned and the mandate is not authorised until the customer completes it. That is valuable context absent from structured fields. Beyond it, nothing is said about idempotency of subscription_ref, retry behavior, provider-specific failure modes, or permissions, so the behavioral picture remains thin for a mutation tool.

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, zero filler: the first front-loads what the tool creates, the second immediately delivers the most consequential return behavior. Nothing is repeated from the title or the schema.

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?

For an 11-parameter, nested, open-world mutation with no output schema and only a single openWorldHint annotation, the description is under-built. It names the returned checkout action but omits prerequisites, provider-specific constraints, what happens on duplicate subscription_ref, and any notion of what a successful response contains beyond the action.

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 36% across 11 parameters with nested objects, so the description is expected to compensate — and it adds nothing about plan, provider, return_url, provider_plan_id, provider_customer_id, provider_options, or metadata. The one genuinely consequential note (total_count being required by Razorpay) lives only in the schema, and the description does not surface the provider-specific requirements an agent would trip over.

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 description uses a specific verb plus resource ('Create a recurring subscription') and names the mandate mechanisms (UPI Autopay / card e-mandate), which is more detail than the title alone. It does not explicitly contrast with siblings such as payments_cancel_subscription or payments_create_payment, though the create/cancel distinction is reasonably self-evident from the name.

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?

There is no statement of when to choose this tool versus payments_create_payment or the other subscription-adjacent sibling, and no preconditions (provider configuration, prior customer creation, or whether a plan must exist first) are given. The only usage signal is implicit: the customer must complete a checkout action, which is described as an outcome rather than as guidance for selecting the tool.

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

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

Goes beyond the readOnlyHint annotation by clarifying the side-effect model: it 'returns files with paths and contents for the agent to write', i.e. nothing is written to disk or to a gateway. That is exactly the disambiguation an agent needs for a generator. It stops short of stating idempotency, cost, or whether generated code is validated.

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, zero filler. The deliverables list is front-loaded and the return contract follows immediately, so an agent gets scope and output shape in one pass.

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 correctly compensates by describing the return as files with paths and contents, which is the essential fact for a generator. Minor gap: it doesn't say whether generated files are complete, framework-idiomatic, or require the agent to fill placeholders for API keys.

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 100% and both enums are self-describing (gateway id, target stack), so the schema carries the parameter burden. The description only loosely echoes the `features` enum values (checkout, webhooks) and never maps provider/framework to their role in output. 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 and artifact ('Generate a working, production-shaped integration') and enumerates exactly what is produced: server routes, client checkout code, env template, test checklist. No sibling tool does code generation, so the agent can distinguish it immediately from verify/create/refund tools.

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?

The phrase 'for a project' implies scaffolding at setup time, but there is no explicit when-to-use, no exclusions, and no routing to siblings like payments_recommend_gateway (which presumably picks the provider) or payments_check_config. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, so safety is covered, and the description adds real value by disclosing the shape of what comes back: feature statuses, payment methods, env vars, constraints, SDKs and platform plugins. It stops short of saying whether the data is static/cached or how large the payload is.

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?

A single front-loaded sentence that identifies the resource first, then the enumerated contents. The parenthetical list is dense but each item is a distinct disclosed return field, so nothing reads as padding.

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 field enumeration is exactly what an agent needs to know what the call yields, and the single-param schema is trivial. The only real gap is the lack of routing guidance against the many sibling tools.

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?

Only one parameter, fully documented in the schema with a type and enum of gateway ids, giving 100% schema coverage. The description adds no extra meaning about the provider argument (e.g. that it must be a supported id from payments_list_providers), so the baseline of 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 resource and scope: a full capability map for exactly one gateway, and enumerates what the map contains. It does not differentiate itself from near-siblings like payments_check_config or payments_list_providers, so an agent must infer the boundary.

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?

No explicit when-to-use or when-not-to-use guidance is given; the agent must infer that this is the discovery call to make before integrating a specific gateway. Nothing tells it why to pick this over payments_check_config or payments_list_providers.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The phrase 'from the gateway' merely restates the open-world hint and adds nothing about what happens with an unknown refund_ref, whether statuses are normalized across providers, or the cost of include_raw round-trips.

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?

A single front-loaded sentence with no waste, but its brevity is under-specification rather than economy — it omits information an agent needs for a six-parameter, multi-provider call.

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, yet the description says nothing about the return shape (status values, per-provider normalization) or how the optional identifiers change the result. For a cross-gateway lookup tool with six params, this leaves meaningful gaps.

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?

Six parameters at 67% schema coverage, and the description mentions none of them. Two parameters (provider_refund_id, provider_payment_id) have no schema description at all, and the description does nothing to explain when those alternatives to refund_ref should be supplied.

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 (fetch refund status) plus the source (gateway), which separates it from payments_get_status (payment status) and payments_refund (create refund). It stops short of naming siblings explicitly, so an agent must infer the distinction from the refund vs payment wording.

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?

There is no statement of when to use this instead of payments_get_status, payments_refund, or payments_verify_payment, and no prerequisites. The agent must infer that this is the read-side counterpart of payments_refund purely from the name and description.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, so the safety and external-call profile is covered. The description adds that this is the authoritative gateway source for reconciliation, which is useful context beyond annotations. It still does not describe error behavior, latency, auth needs, or return details.

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?

The description is a single front-loaded sentence with no filler. It states the action and the reconciliation context immediately.

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?

For a read-only status lookup with annotations covering safety and external access, the description is minimally adequate. However, with no output schema and a reconciliation-critical purpose, it is thin on what status data is returned and how optional parameters like include_raw and provider_order_id should be used.

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 75%, with provider, order_ref, and include_raw documented in the schema. The description adds no parameter-level semantics and does not compensate for provider_order_id being undocumented. A 3 reflects adequate schema coverage with a remaining gap.

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 description uses a specific verb and resource: fetching payment status from the gateway. The phrase 'source of truth for reconciliation' gives useful scope. It does not explicitly differentiate from siblings such as payments_verify_payment or payments_get_refund_status, so it falls short of a 5.

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?

The reconciliation/source-of-truth framing implies when this tool is useful, but it gives no explicit when-not guidance or named alternatives. An agent must infer that verification and refund-status checks belong to other sibling tools.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description contributes beyond the annotation by enumerating the returned content (one-line summary, credential configuration status, feature support matrix), which matters since there is no output schema. It does not mention ordering or whether the list can change, but the added disclosure is substantive.

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?

A single sentence that front-loads the action and scope, then lists what is returned. Every clause carries information an agent would otherwise have to discover by calling the 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 parameters, no output schema, and a read-only annotation, the description must carry the return-shape burden, and it does by naming the three payload elements. Only the relative positioning against overlapping sibling tools is left unaddressed.

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?

The tool takes zero parameters, so the baseline is 4; there are no arguments whose meaning the description could clarify. The schema is empty and fully documented, so nothing more is needed on this dimension.

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 (list) and resource (every supported gateway), plus what each entry contains. It is clear on its own, but it never contrasts itself with close siblings such as payments_get_capabilities or payments_check_config, which appear to overlap with the feature-matrix and credential-status information it returns.

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?

There is no explicit when-to-use or when-not-to-use guidance and no named alternative. The overview/discovery use case is implied by 'list every supported gateway', which is enough for an agent to infer intent but leaves ambiguity against payments_get_capabilities and payments_check_config unresolved.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds domain semantics (settlements are gateway-to-bank payouts) but says nothing about pagination limits, default date range when from/to are omitted, or the shape/volume of results — relevant given an open-world listing.

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?

A single tight sentence, front-loaded with the action and resource, with the parenthetical definition earning its space. No filler.

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 could describe what a settlement record contains (amount, fee, settlement date, status) or that results are date-bounded. As written it is sufficient to select the tool but thin for interpreting the response in a reconciliation workflow.

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 75%: from/to carry YYYY-MM-DD formats and provider carries a gateway-id description plus an 8-value enum. The description adds no parameter-level meaning beyond the resource itself, and 'count' has no schema description at all, so the one genuinely ambiguous parameter (page size? max results?) is left 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 and resource ('List settlements') and immediately defines the term as 'payouts from the gateway to your bank', which an agent needs since 'settlement' is ambiguous in payments contexts. It does not distinguish itself from siblings explicitly, but the siblings are almost all different resources (payments, refunds, subscriptions, providers), so confusion risk is low.

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?

'for reconciliation' implies the use case but names no alternative tool, no when-not condition, and no prerequisite. It is enough for an agent to know this is a reporting/reconciliation read rather than a lookup-by-id operation, but nothing more.

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

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.

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

readOnlyHint=true already tells the agent this is a safe read. The description adds the useful detail that rankings come from the capability map, but it does not say what the response contains (ordered list plus generated explanation), whether results are deterministic, or how ties are resolved. Adequate but not rich.

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?

A single front-loaded sentence with no filler, and the action verb comes first. It is slightly over-compressed given the missing return-value information, but nothing in it is wasted.

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 only two parameters, one required, and no output schema, the description should carry the burden of describing the return shape and how 'business' is used. It hints at an explanation but never states that an explanation is returned or that 'business' is ignored for ranking.

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 100%, so both parameters are already documented in the schema. The description echoes the example needs but adds nothing about ordering semantics of 'needs' (most important first) or whether 'business' influences ranking versus only the explanation text. Baseline 3 is appropriate.

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 ('Rank gateways') plus the mechanism ('using the capability map'), and the parenthetical examples pin down the kind of use case. It is distinguishable from payments_list_providers and payments_get_capabilities because it produces a ranking rather than a listing, though the description never names those siblings explicitly.

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?

The parenthetical examples ('subscriptions, international payments, Shopify, lowest integration effort') imply when to reach for this tool, but there is no explicit statement of when to use it versus payments_get_capabilities or payments_list_providers, and no exclusions or prerequisites.

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

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

Annotations declare destructive, idempotent and openWorld, so the safety bar is partly met by structured data; the description nonetheless adds the key semantics: refund_ref as idempotency key with replay-returns-same-refund behavior and the OUTCOME_UNKNOWN non-retry rule. It does not say what a partial refund does to subsequent refundable balance or whether instant speed carries extra cost.

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 sentences, each with a distinct job: what it does, idempotency, failure recovery, money-movement safety. The safety-critical instruction is last-sentence prominent and nothing is padded.

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?

For a destructive, open-world money-movement tool with 9 params and no output schema, it covers purpose, idempotency, uncertain-outcome recovery and approval gating. An agent has enough to invoke correctly and to avoid a duplicate refund.

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 67% and the description supplies the two most consequential semantics not fully in the schema: refund_ref is an idempotency key for safe resends and confirm=true is gated on human approval in live mode. It leaves speed, reason, include_raw and provider_payment_id unexplained, so it doesn't fully compensate for the remaining coverage gap.

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+resource+scope: 'Refund all or part of a captured payment.' It also distinguishes itself from sibling retrieval tools by naming payments_get_refund_status and payments_get_status as recovery paths rather than refund paths.

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 routing: on OUTCOME_UNKNOWN, check the two status tools BEFORE retrying, and in live mode ask the human first, then pass confirm=true. This gives when-to-use, when-not-to-retry, and the prerequisite gate in three compact sentences.

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

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

Adds real behavioral context beyond readOnlyHint: the payload is signed with the provider's real scheme and the caller's webhook secret, the tool is disabled in live mode, and secrets must not be reused in production. Return shape is sketched ('headers + raw body') rather than fully specified.

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 the tool produces, followed by mode constraints and a safety note. No filler.

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?

For a read-only generator with no output schema, the description covers what it emits, the sandbox-only constraint, and the security caveat. The main remaining gap is parameter guidance for the 8 inputs, which the description leaves entirely to the schema.

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?

The description names no parameters at all despite 8 inputs, 4 required, and only 63% schema coverage. It never explains the relationship between the event type and refund_ref, nor what target_url does (the curl output is documented only in the schema), so it adds no meaning over the schema.

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 product ('Produce a correctly signed webhook (headers + raw body) for local testing'), which cleanly separates it from the verify_webhook sibling that consumes rather than emits a webhook. The scope (signed payload generation) is unambiguous without opening the 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?

Clear context: sandbox mode, local endpoint, replay with curl. It does not name the alternative tool for consuming webhooks (payments_verify_webhook) or state what to do when you need a live endpoint, so exclusions are only partially covered.

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

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.

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

readOnlyHint=true is consistent with a verification operation, and the description adds real behaviour beyond the annotations: the output is normalised into named common events (with examples), and the input must be the untouched raw body or the signature check will fail. It omits the failure path (what happens on an invalid signature) and whether any state is recorded, which keeps it short of a 5.

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 short sentences, zero waste, with the primary action front-loaded and the critical input constraint as a distinct imperative sentence.

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 usefully sketches the return value as a normalised event, which is the key thing an agent needs. But for a 4-parameter tool with a required nested object, it leaves the headers parameter and error behaviour unexplained — the agent cannot predict what an invalid signature yields.

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 only 50% (provider and include_raw documented; headers and raw_body have no schema description). The description compensates well for raw_body by mandating the exact raw string, but says nothing about the required nested `headers` object — the agent must infer that it is the provider's request headers verbatim.

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 description gives a specific verb and resource ('Verify a webhook signature') plus a second concrete outcome ('normalise it into a common event (payment.succeeded, refund.processed, ...)'), so the agent knows exactly what it gets back. It does not name the nearest sibling (payments_simulate_webhook), so differentiation is only implicit.

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?

Usage is implied by the nature of the tool — you call it on an incoming provider webhook before acting on it — and 'Pass the RAW body string exactly as received' prevents the classic failure mode of verifying a re-serialised body. However, there is no explicit when/when-not statement and no pointer to payments_simulate_webhook or payments_verify_payment as alternatives.

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