Pin Payments MCP by usefulapi

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds nothing beyond restating the HTTP method and path, giving no info on what is returned or how missing/invalid tokens behave.

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 fragments, front-loaded with the resource and scoping constraint; no filler. It is arguably too terse rather than verbose.

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?

The tool is simple (one required param, rich annotations, no output schema), so the low bar is partially met. Still, no mention of the not-found behavior or what an authorisation object represents leaves a small gap for an agent.

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 parameter already includes a concrete example, so the schema carries the load. The description's 'auth_...' prefix mention reinforces but does not extend 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+resource: fetch a single authorisation by token, with the token prefix convention given inline. This implicitly separates it from pinpayments_list_authorisations, though no sibling is named 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?

There is no when-to-use/when-not guidance and no mention of the list_authorisations alternative or of error conditions for an unknown token. Only a bare scoping hint ('by token') is present.

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 readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds real value beyond that: it defines the semantics of 'available' vs 'pending' and specifies the unit convention ('base unit, cents for AUD'), which the agent cannot infer from the empty schema. Auth requirements and rate limits are not mentioned, keeping it below 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?

One information-dense sentence plus the endpoint, with the resource and its two components front-loaded. Every clause adds meaning — the pending definition and the unit convention both matter to correct interpretation.

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 carries the burden of describing return values, and it does cover the key shape (available, pending, per currency, base units). It stops short of specifying whether the response is keyed by currency or an array, which is the only real omission for a zero-parameter read tool.

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. The description reinforces this with 'per currency' and the bare 'GET /balance' endpoint, making clear no filters or IDs are accepted.

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 (the Pin Payments account balance) with its two components, available and pending, and defines what each means. The parenthetical definitions and the 'per currency' scope make it unmistakable against siblings like get_charge or get_transfer, which all operate on a resource ID.

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 only implied — an agent reading 'current account balance' can infer it's for checking funds before a transfer, but the description never says when to reach for it or names any related tool (e.g. list_transfers) as an alternative. There is no alternative tool for balance, which softens the gap, but no explicit context is given.

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 readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds genuine value by disclosing what the response contains (fees, refunds total, settlement transfer state, chargeback flag) and mapping it to the REST endpoint — useful behavioral context beyond the annotations.

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 tight fragments: the payload summary front-loaded, endpoint last. Every clause earns its place with zero 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 one-parameter read tool with no output schema, the description supplies the missing return-value picture and the endpoint mapping. It's essentially complete for correct invocation, with only sibling routing left implicit.

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% with a single required charge_token and an example value, so the schema carries the parameter semantics. The description only echoes the ch_... token form, adding no syntax beyond what the schema already documents; 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 ('One charge by token') and enumerates the notable fields returned, plus the underlying GET /charges/{token} endpoint. This distinguishes it from list_charges and search_charges by emphasizing single-charge retrieval, though it doesn't name 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?

'One charge by token' implies retrieval of a single record versus the list/search siblings, but there is no explicit statement of when to prefer this tool or what prerequisite (a known ch_... token) selects it. 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the underlying REST endpoint (GET /customers/{token}), which is mildly useful context but does not mention error behavior (e.g., 404 for unknown token) or the shape of the returned customer.

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 fragments with zero waste, leading with the scope and following with the endpoint. Nothing extraneous is included.

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 getter with full schema coverage and complete annotations, no output schema, this is largely sufficient. The only gap is the absence of any error/not-found guidance, which is minor for such a simple tool.

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 the single parameter documents the token format with an example, so the schema carries the parameter semantics. The description's '(cus_...)' reinforces the prefix but adds nothing beyond 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 resource (customer) with a singular scope ('One customer by token') and gives the token prefix, making it distinguishable from the sibling list_customers. It omits an explicit verb in the description text, relying on the title 'Get customer' to convey retrieval.

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 singular framing ('One customer by token') implies use when the token is known, contrasting implicitly with list_customers. However, there is no explicit when-to-use statement, no mention of alternatives such as list_customers, and no note on what to do if the token is unknown.

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, idempotentHint=true, destructiveHint=false, so the safety profile is covered by structured data. The description adds only the HTTP route; it says nothing about error behavior for invalid tokens or the shape of the returned deposit, which for an openWorld API tool would be valuable.

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 terse fragments, front-loaded with the resource identity and followed by the endpoint; every word carries information 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 single-parameter read with fully documented schema and annotations covering safety and idempotency, the definition is nearly sufficient. The only gap is that with no output schema, nothing hints at the deposit fields returned, though this is minor for a straightforward lookup.

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 the deposit_token parameter already documents the dpo_ prefix and an example value, so the description's 'dpo_...' restates schema content. 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 ('One deposit by token') plus the underlying endpoint GET /deposits/{token}, so the retrieval semantics are unambiguous. 'By token' implicitly contrasts with the list_deposits sibling, but no sibling is named 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 singular 'one deposit by token' implies this is the lookup path versus pinpayments_list_deposits, but the description never states when to use this instead of the list tool or how to obtain a token. Usage is inferable rather than declared.

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, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds only the endpoint path and token prefix, with no note on error behavior for an unknown token or on what a dispute record contains.

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 clauses, zero filler, with the resource identified first and the endpoint 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 one-parameter read with no output schema, the essential inputs are covered and annotations handle safety, but nothing describes what the returned dispute object looks like or how it relates to get_dispute_activity. Adequate, with a clear 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 100% and the single parameter already carries a concrete token example, so the description's '(dis_...)' hint is largely redundant. Baseline 3 applies when the schema does the work.

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 retrieval of a single dispute resource and pins the identifier format (dis_...) plus the underlying endpoint, which implicitly separates it from the list/search dispute siblings. It does not explicitly name those siblings, 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?

'One dispute by token' implies single-record lookup versus the list_disputes/search_disputes alternatives, but the description never states when to use this instead of pinpayments_search_disputes or pinpayments_get_dispute_activity. Usage is inferable but not 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 readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds real value by enumerating what the feed contains (status changes, chargeback fees, recoveries) and pinning the exact endpoint. It stops short of saying whether the feed is paginated, capped, or ordered.

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 tight sentences: the resource and its contents come first, the endpoint second. No filler, no repetition of the title.

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 single-resource fetch with no output schema, the description conveys enough about the returned data (status changes, ledger entries) to call it correctly. Pagination and result ordering are the only notable 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?

With a single parameter and 100% schema description coverage, the schema already documents the dispute_token format ('dis_...'). The description only restates it via the 'GET /disputes/{token}/activity' path, adding no extra constraint or semantics beyond what the schema provides.

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: 'the activity feed of one dispute', with concrete contents (status changes, ledger entries such as chargeback fees and recoveries) and the endpoint path. This is clearly distinguishable from pinpayments_get_dispute and pinpayments_list_disputes, though it 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?

Usage is only implied: you call it to inspect one dispute's activity. There is no statement of when to prefer this over pinpayments_get_dispute or pinpayments_search_disputes, and no prerequisites such as needing a dispute token obtained elsewhere.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description adds only the HTTP endpoint and token format, neither of which provides meaningful behavioral context beyond what the structured metadata and schema already convey.

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 two short sentences with zero wasted words, and the core operation and identifier are front-loaded.

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 simple one-parameter retrieval tool with full schema coverage and rich annotations, the description is minimally adequate. It does not describe the response shape or any error behavior, but the low complexity limits the practical 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 100%, so the single event_token parameter is already fully documented in the schema. The description mentions the token format, but adds no syntax or semantic detail beyond the schema, making the baseline 3 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?

The description states a specific retrieval action ('One event') and identifier ('by token (evt_...)'), and the endpoint 'GET /events/{token}' makes the resource explicit. It implicitly distinguishes itself from list_events by specifying a single event, though it does not name the sibling alternative.

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 'by token': use this when you have an event token. However, there is no explicit when-to-use guidance, no exclusions, and no direct comparison to the sibling list_events 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered without the description. The description adds only the REST endpoint mapping, saying nothing about what a not-found token returns or any auth/rate-limit expectations.

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 fragments with zero filler and the key constraint (single plan, by token) front-loaded. It is efficient, though terse enough that it reads more like a signature than a definition.

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 tool with rich annotations this is close to sufficient, but there is no output schema, so the description could have said what a plan object contains; that omission leaves the agent without any expectation of the return payload.

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 the plan_token property already carries the plan_... example, so the description's '(plan_...)' restates schema content rather than adding meaning. Baseline 3 applies when the schema does the heavy lifting.

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 the specific resource (plan), cardinality (one) and lookup key (token), plus the underlying endpoint GET /plans/{token}. That distinguishes it clearly from the sibling pinpayments_list_plans, though it never names the sibling 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?

'One plan by token' implies the retrieve-by-identifier use case, but there is no explicit when-to-use guidance, no statement that pinpayments_list_plans should be used to discover tokens, and no mention of error behavior for an unknown token.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds only the REST endpoint mapping and the rp_ token prefix; it says nothing about behavior when the token is unknown/expired or what the recipient object contains.

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 terse fragments with the key scoping information (one, by token) front-loaded and no filler. The terseness borders on under-specification rather than verbosity, which is the right kind of failure for a simple get.

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?

A one-parameter read tool with rich annotations and no output schema does not need much, and this covers the mechanics. However, nothing explains the recipient resource itself (payout destination, linked to transfers) or failure behavior, which matters given 35 sibling get_* tools an agent must choose between.

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 parameter is documented in the schema with an example token, so the baseline is 3. The description repeats the rp_ prefix convention but adds no constraints beyond the schema's maxLength/minLength.

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 (recipient) retrieved by singular token, and the "One recipient by token" phrasing implicitly separates it from pinpayments_list_recipients. It lacks an explicit sibling callout, so an agent has to infer the differentiation from the 'one' vs 'list' 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?

Usage is only implied: needing a single recipient whose token you already hold. There is no statement of when to prefer this over pinpayments_list_recipients or pinpayments_list_recipient_transfers, and no prerequisite/permission context.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds only the HTTP endpoint mapping, saying nothing about 404 behavior, auth requirements, or response shape.

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 fragments, front-loaded with the core purpose and zero padding. The endpoint restatement is lightly redundant with the name but useful for API mapping.

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 say what a refund record contains or what happens for an invalid token, but it doesn't. Annotations and a single fully documented parameter keep it minimally viable rather than complete.

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 the token example with the rf_ prefix is documented in the schema itself. The description merely echoes the rf_... format, adding no new semantics; 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 ('One refund by token') plus the API endpoint, making it distinguishable from list_refunds and list_charge_refunds. It only loosely restates the title 'Get refund', but the scope qualifier 'one' and token format add real clarity.

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 only implied: an agent can infer it should call this when it holds a refund token. No explicit when-to-use guidance or routing against siblings such as pinpayments_list_refunds or pinpayments_list_charge_refunds.

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 readOnly, idempotent, non-destructive, and open-world behavior, so the safety profile is fully covered. The description adds only the REST endpoint path; it says nothing about auth requirements, behavior on an unknown token, or what the response contains. With annotations carrying the load, a 3 is fair.

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, front-loaded sentences with no filler. However, the second sentence ('GET /subscriptions/{token}') largely restates the first, so a small amount of the text does not earn its place.

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?

A simple one-parameter getter whose schema and annotations are complete, so little is required. Still, with no output schema, the description gives no indication of what the returned subscription object contains, which is the main remaining 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 coverage is 100% and the single parameter is documented with an example token in the schema itself. The description's '(sub_...)' hint merely restates that, adding no new syntax or format information. 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+resource ('One subscription by token') and names the token prefix, which cleanly separates it from list_subscriptions and get_subscription_ledger. It doesn't explicitly contrast with those siblings, so it stops 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?

Usage is only implied: fetch a single subscription when you already hold a token. There is no explicit 'use list_subscriptions to find a token first' or any statement about when not to call 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 already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds only that entries are credits and debits; it says nothing about pagination behavior, ordering, or result volume, all of which matter for a ledger 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?

Two short fragments, front-loaded with what is returned before the endpoint reference. Nothing wasteful, though the second fragment is arguably redundant with the tool name and annotations.

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, so the description carries the burden of describing return values. It hints at credits/debits but does not describe entry fields, ordering, or pagination across pages, leaving the agent with only a thin picture of what comes back.

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 both parameters are documented there, including pagination semantics ('page number, from 1'; 'pass the previous reply's next_page'). The description only restates the token via the path template, adding no meaning beyond 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?

Names the specific resource (ledger entries of one subscription) and clarifies what a ledger entry is (credits and debits), and the endpoint template pins down the scope. It cannot be confused with pinpayments_get_subscription, which returns the subscription itself rather than its ledger.

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 guidance on when to use this instead of pinpayments_get_subscription or the other list/get siblings, and no prerequisites or exclusions. The agent must infer usage from the endpoint line alone.

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 cover the full safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), so the description is not obligated to restate them. What it adds — 'GET /transfers/{token}' — only restates the read semantics already declared, and it says nothing about error behaviour such as a 404 for an unknown token. That is adequate-but-minimal given annotation coverage.

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 clauses with zero filler, and the identifying token format is front-loaded. It is efficient but verges on under-specification rather than tight writing, which keeps it off a 5.

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 with full annotations and no output schema, the definition is complete enough to invoke correctly. It omits any note on not-found behaviour or what the returned transfer object contains, leaving the agent to discover these at call time.

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 the single parameter already carries the token format and an example ('tfer_lfUYEBK14zotCTykezJkfg'). The description's 'tfer_...' prefix hint is a useful reinforcement for the agent but duplicates what the schema already documents, so 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 ('get'), resource ('transfer'), and identifier form ('by token (tfer_...)'), which is enough to distinguish it from the many get_* siblings since each targets a different resource. It stops short of explicitly contrasting with pinpayments_list_transfers or pinpayments_search_transfers, but the resource noun does the discriminating work.

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 guidance on when to choose this over pinpayments_list_transfers or pinpayments_search_transfers, and no note that a transfer token is required as a precondition. The only implied usage is the bare fact that it retrieves a single record, which an agent could infer from the name alone.

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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely useful semantics beyond that: that these are uncaptured held funds with a seven-day expiry, and which fields (amount, amount_captured, amount_remaining, expired) come back. It does not mention pacing or rate limits, so it is strong rather than exhaustive.

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 padding, with the identifying concept and the return fields front-loaded before the endpoint reference. Every clause carries information an agent can use.

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 names the returned fields, and the annotations carry the safety and idempotency profile. For a single-optional-parameter list tool this is nearly sufficient; only the pagination behaviour and the empty-result case are left unstated.

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 the single page parameter is fully documented in the schema, including the 25-per-page size and the next_page chaining hint. The description adds nothing about pagination, so the baseline 3 for a fully documented schema 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?

Specific verb (List) plus resource (card authorisations), and it defines the concept inline — held funds not yet captured that expire after seven days — which tells an agent exactly what domain object is being enumerated. The List/Get distinction against pinpayments_get_authorisation is evident from the naming, and the endpoint note (GET /authorisations) confirms scope.

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 never states when to reach for this tool over pinpayments_get_authorisation or the other list siblings, and offers no prerequisites or exclusions. The domain gloss on what an authorisation is helps indirectly, but there is no explicit routing guidance for an agent choosing among 34 siblings.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered. The description adds no behavior beyond restating the endpoint: nothing about pagination behavior, empty results, or result ordering. With annotations doing all the work, this contributes little.

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 terse sentences with the scope stated first; nothing is padded. The raw endpoint path is somewhat redundant given the title and name already convey the operation, but it's compact and front-loaded.

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 simple two-parameter read-only list, the description plus a fully documented schema is nearly sufficient. However, it says nothing about what a refund record contains or pagination flow (the schema covers paging but the description doesn't reinforce it), leaving a modest 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 100% — charge_token format (ch_...) and the page parameter with its 25-per-page and next_page guidance are both documented in the schema. The description adds no parameter meaning beyond that, 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 (refunds) with a precise scope (refunds issued against a single charge), plus the underlying endpoint GET /charges/{token}/refunds. It implicitly distinguishes itself from the sibling pinpayments_list_refunds (all refunds) and pinpayments_get_refund (single refund), though it never names either alternative.

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 only implied: the phrase 'issued against one charge' tells an agent this is the scoped variant of listing refunds, but there is no explicit when-to-use, when-not, or pointer to pinpayments_list_refunds for cross-charge queries.

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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavior: fixed 25-per-page pagination and, notably, that card data is redacted to scheme plus last four digits — a compliance-relevant detail an agent can't get elsewhere.

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?

Purpose and page size are front-loaded, followed by a compact field list; there is no filler. The trailing field enumeration is dense but each item earns its place as return-value disclosure, given no output schema exists.

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, enumerating returned fields (amount in base units, status_message/success, total_fees, chargebacks flag, etc.) fills the biggest gap and does so well. Missing only guidance on filtering and on total-count/termination behavior for pagination loops.

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 and its schema description is fully covered (100%), including the next_page chaining hint, so the baseline is 3. The description's "25 per page" merely restates the schema's page-size note and adds no format or edge-case meaning.

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 charges (card payments)") and grounds it with the underlying endpoint, GET /charges, which implicitly distinguishes it from pinpayments_list_customer_charges and pinpayments_search_charges. It never explicitly names those siblings, though, so an agent must infer the boundary from the endpoint.

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?

Provides no when-to-use or when-not guidance and never mentions the obvious alternatives (pinpayments_search_charges for filtered lookups, pinpayments_list_customer_charges for per-customer listing). The only navigation help is the schema's own "pass the previous reply's next_page", which lives in structured data, not the 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds genuine value beyond that by disclosing the field projection — only scheme, last four digits, and country are returned, with token, expiry, and address withheld — which sets expectations about what data the agent will and won't get. Pagination specifics (25 per page) are left to the schema.

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 plus an endpoint reference, with no filler. The most decision-relevant detail, the restricted field projection, is placed before the endpoint.

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 important work by enumerating the returned fields and explicitly noting what is omitted. The only gap is that multi-page behavior and empty-result handling aren't described, but pagination mechanics are covered by the schema's page parameter.

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 parameters (customer_token, page) are documented in the schema itself, including the cus_... token format and the 25-per-page pagination hint. The description adds nothing about parameters beyond that, 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?

The description names a specific resource ('Cards stored for one customer') and scopes it precisely, plus the underlying endpoint GET /customers/{token}/cards. It is clearly distinguishable from siblings like pinpayments_list_customer_charges or pinpayments_list_customer_subscriptions, though the verb 'list' is implied rather than stated outright.

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 routing to alternatives such as pinpayments_get_customer (for the customer itself). The reader must infer that this tool is for enumerating cards only, rather than for fetching a single card or the customer record.

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 readOnly, idempotent, non-destructive, openWorld, so the safety profile is covered. The description adds the endpoint path and the per-customer scoping constraint, but says nothing about ordering, volume, or pagination behavior beyond what the schema's page field states.

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 fragments with zero waste, front-loading the resource scope. It is arguably too terse for a tool with a same-resource sibling, but nothing is redundant.

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 simple two-parameter read tool with full schema coverage and complete annotations, the essentials are present. The notable gap is sibling routing against pinpayments_list_charges and pinpayments_search_charges, which an agent must infer.

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 customer_token and page (including the 25-per-page and next_page guidance) are fully documented in the schema. The description adds no parameter meaning beyond echoing the customer token in the path. 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 resource (charges) with a scope qualifier (made by one customer) and reinforces it with the exact REST endpoint. It is distinguishable from pinpayments_list_charges, though the differentiation is implicit rather than spelled out.

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 per-customer scoping implies you should use this when you have a customer token rather than searching all charges, but no alternative (pinpayments_list_charges, pinpayments_search_charges) is named and no when-not condition is given.

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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds useful context beyond that: a fixed page size of 25 and the exact shape of returned records, which matters because there is no output schema.

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?

One front-loaded sentence carrying scope, page size, return fields and endpoint, with no filler. The field enumeration is long but earns its place because no output schema exists.

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 responsibly enumerates the returned fields and states the page size, and the schema covers the page parameter. The only gap is that it never explains the pagination termination signal (next_page) that the schema parameter references.

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 'page' parameter is fully documented in the schema, including the 'Pass the previous reply's next_page' hint. The description adds no parameter semantics of its own, 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?

Specific verb + resource ('List stored customers') plus the exact field set returned and the underlying endpoint (GET /customers). The plural 'list' vs. the singular sibling pinpayments_get_customer is implied by the naming and the field enumeration, but no sibling is explicitly named.

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 only implied: the word 'List' signals a browse-all operation versus pinpayments_get_customer for a single record, but the description never states when to use this tool, when not to, or which sibling to prefer for filtered lookups (e.g. customer cards or charges).

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, idempotentHint, openWorldHint, and non-destructive behavior. The description adds the returned attributes and GET endpoint, but does not cover auth requirements, rate limits, or pagination behavior beyond what the schema states.

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?

Extremely concise and front-loaded: scope and returned fields appear first, then the endpoint. Every clause earns its place with 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 simple read-only list with rich annotations and full schema coverage, the definition is nearly complete: it gives scope, fields, and endpoint. The only minor gap is that pagination/default page behavior is left to the schema rather than mentioned in the description.

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 does not add syntax or meaning beyond the schema, which is acceptable at baseline 3.

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: subscriptions of one customer, and lists the returned fields. The scope 'of one customer' clearly distinguishes it from list_subscriptions and list_plan_subscriptions, and the endpoint confirms the operation.

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 'one customer' scoping gives clear context for when to use this tool over the broader subscription listers, but it does not explicitly name alternatives or exclusions. The usage is strongly implied rather than fully guided.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds the returned field names and the REST endpoint, but says nothing about ordering, pagination behavior beyond the schema, or rate limits.

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?

One sentence plus the endpoint, front-loaded with the action and scope and with zero filler. Every clause carries 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?

For a simple single-optional-parameter read tool with no output schema, enumerating the returned fields (amount, currency, bank narration, available_at) fills the return-value gap well. Missing only ordering/total-count expectations, which are minor.

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 the single page parameter is well documented there, including the 25-per-page size and the next_page chaining hint. The description contributes no additional parameter meaning, 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 ('List deposits made to the account'), names the key returned fields, and cites the underlying endpoint GET /deposits. The list-vs-get distinction against sibling pinpayments_get_deposit is evident from the name and wording, though it is never made explicit.

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 guidance on when to use this versus pinpayments_get_deposit or the other list/search siblings, and no prerequisites or exclusions are stated. The endpoint reference implies read-only enumeration but provides no usage conditions.

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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description contributes beyond that by enumerating the fields the response carries (category, status, amount, disputed charge, evidence_required_by, evidence types), which substitutes for the absent output schema.

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 compact elements: a field inventory and the endpoint, with the purpose front-loaded. The field list is dense but earns its space given there is no output schema; nothing is redundant.

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 sparse, read-only list tool this is largely adequate — pagination and sort semantics live in the schema and return fields are named in the description. The notable gap is routing: it never explains how it relates to search_disputes or get_dispute, which is the main ambiguity an agent faces here.

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 all three parameters (page, sort, direction) carry their own descriptions and enums, so the description adds nothing parameter-specific. 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 clear verb+resource ('List chargeback disputes') and even enumerates the returned attributes plus the underlying endpoint GET /disputes. It never distinguishes itself from the sibling pinpayments_search_disputes, so the agent must infer that this is the unfiltered listing variant.

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 only implied by the 'List' verb and the 'GET /disputes' route; there is no explicit statement of when to choose this over pinpayments_search_disputes or pinpayments_get_dispute. No exclusions or prerequisites are given.

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, idempotentHint, non-destructive and openWorld, so the safety profile is covered. The description still adds real value beyond that by disclosing data redaction (“cards masked”) and the shape of each entry (event plus affected record), which the annotations cannot convey.

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?

One dense sentence: resource, example event types, redaction note, and endpoint, all front-loaded with zero filler. Nothing could be cut without losing 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?

For a one-parameter read-only list tool this is complete — event content, masking, and pagination are all covered. With no output schema the description could have said more about the response envelope, but the essentials an agent needs are 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% and the lone `page` parameter is fully documented in the schema, including the 25-per-page size and the next_page handoff. The description adds nothing about pagination or iteration, 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?

The description names the resource precisely (the account's event log) and gives concrete event-type examples (charge.captured, refund.created, dispute.updated), so an agent knows exactly what comes back. It implies listing semantics rather than stating the verb, and it doesn't explicitly contrast with pinpayments_get_event, keeping it just 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?

Usage is only implied: an agent can infer this enumerates all events while pinpayments_get_event fetches a single one, but the description never says so. There are no exclusions or prerequisites, so the reader must reason from the sibling names alone.

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 readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds real value by naming the exact fields returned (amount, currency, interval, trial/setup amounts, subscription counts by state) and the underlying endpoint, which matters because no output schema exists.

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 the field list and endpoint appended; every element earns its place and nothing is redundant.

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, listing the returned fields is exactly the right compensation, and pagination is fully handled by the schema. Only the absence of sibling routing guidance keeps it from being complete.

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?

There is one parameter with 100% schema description coverage, including the 25-per-page size and the next_page chaining hint, so the schema carries the semantics. The description adds nothing about pagination, 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 ('List subscription plans') and enumerates the fields returned, with the underlying endpoint GET /plans. It is distinguishable from pinpayments_get_plan by the list-vs-get distinction, though it never explicitly contrasts with pinpayments_list_plan_subscriptions.

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 only implied by the 'List' verb and the plan context; the description never states when to use this versus get_plan (single plan) or list_plan_subscriptions (plans' subscriptions). Adequate but leaves routing to inference.

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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered. The description adds no behavioral context of its own — no note on result ordering, pagination limits beyond the schema, inclusion of canceled subscriptions, or external API failure behavior.

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 with no filler, and the endpoint is front-loaded. But the brevity comes from under-specification rather than economy — there is essentially no informational content to compress.

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 simple read-only, two-parameter list endpoint with full schema coverage and complete annotations, the bare minimum is arguably met. Still, the description never states what the call returns or whether the plan must exist/be active, leaving an agent to rely entirely on structured fields.

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 parameters (plan_token, page) are documented in-schema, including page size and the next_page chaining hint. The description adds no meaning beyond the schema; 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?

The description identifies the resource and narrows it to one plan ("Subscriptions to one plan"), implicitly distinguishing it from pinpayments_list_subscriptions and pinpayments_list_customer_subscriptions. However, it is a noun fragment with no verb (list/fetch) and adds nothing beyond the title and the raw endpoint path, so an agent has to infer the action.

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 the near-identical siblings pinpayments_list_subscriptions or pinpayments_list_customer_subscriptions, and no prerequisites. The only hint is the phrase "to one plan," which implies the plan_token is the selector, but no explicit routing guidance is given.

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, idempotentHint, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful return-field context and the endpoint, but does not add behavioral details such as auth requirements, rate limits, or pagination beyond what the schema provides.

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 the resource, returned fields, and endpoint. There is no filler, and the key information is presented 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 simple read-only list operation, the annotations cover safety, the schema covers pagination, and the description enumerates returned fields. It is nearly complete, though it could explicitly mention pagination behavior or when to prefer the single-recipient sibling.

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 the page parameter is fully documented in the schema, including default, maximum, page size, and next_page guidance. The description adds no parameter semantics beyond the schema, so the baseline of 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?

The description states a specific verb and resource, 'List transfer recipients', and adds the returned fields plus the endpoint 'GET /recipients'. It is clear, but it does not explicitly distinguish itself from sibling tools such as get_recipient or list_recipient_transfers.

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 list verb and plural resource, suggesting a collection-listing operation. However, there is no explicit when-to-use guidance or routing to alternatives like get_recipient for a single recipient.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds the underlying endpoint (GET /recipients/{token}/transfers), which helps an agent map behavior to the API, but it says nothing about result set size, ordering, or pagination semantics beyond what the schema states.

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 fragments, front-loaded with the scope before the endpoint mapping. Nothing is wasted, though the raw HTTP endpoint is of marginal value to an agent that already has the tool name and 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?

With only 2 params, complete schema coverage, and no output schema, the description needs little – but since there is no output schema, a hint about what a transfer record contains or how results are paged back would have closed the gap. As written it is minimal but not misleading.

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%: both recipient_token (rp_... format) and page (page number, 25 per page, use previous next_page) are fully documented in the schema. The description adds nothing about parameters, which is acceptable given the schema does the work, so 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?

The description names a specific resource and scope: transfers paid to a single recipient, distinguished from the generic list_transfers by 'to one recipient'. It stops short of explicitly naming the sibling it differs from (pinpayments_list_transfers, pinpayments_search_transfers), 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?

There is no when-to-use or when-not-to-use guidance, and no alternative is named. The only cue is the scoping phrase 'one recipient', which implies usage but gives no exclusions or prerequisites (e.g., when to prefer search_transfers or list_transfers).

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 establish readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description usefully adds the page size of 25 and the GET /refunds endpoint, but says nothing about auth requirements, rate limits, or ordering of results beyond the default.

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 that front-loads the action and page size, then enumerates fields and the endpoint. The field list is dense but earns its place given there is no output 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?

With no output schema, enumerating returned fields (amount, currency, charge token, status_message, error_message, created_at) is genuinely useful and covers most of what an agent needs to interpret results. What's left out is the relationship to the per-charge refund listing and any indication of result ordering or filtering capability.

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 sole parameter's description already explains paging and the '25 results per page' behavior with next_page feedback. The description's '25 per page' merely restates the schema, adding no new meaning beyond 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?

The description gives a specific verb and resource ('List all refunds') and even names the endpoint, so an agent immediately knows this is a paginated collection read. It stops short of distinguishing scope from the closely related siblings pinpayments_list_charge_refunds (refunds for one charge) and pinpayments_get_refund (single refund), which is the one ambiguity an agent faces here.

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 tool versus pinpayments_list_charge_refunds or pinpayments_get_refund; both alternatives appear in the sibling list and are easy to confuse with an account-wide refund listing. Usage is only inferable from the name and the field list.

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 that this is a read-only, idempotent, non-destructive operation, so the safety profile is covered. The description adds the endpoint and the fields returned, which is useful context, but it does not discuss pagination behavior, auth needs, or rate limits beyond what the schema provides.

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 two compact sentences front-loading the resource and then the returned fields, with no wasted prose. Every element—scope, field list, and endpoint—adds useful 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?

For a simple read-only list endpoint with rich annotations and a fully documented schema, the description is largely complete: it says what is listed, what fields appear, and the endpoint. The main remaining gap is sibling differentiation, since it does not clarify when to prefer this over the customer- or plan-specific list 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?

Schema description coverage is 100%, and the single 'page' parameter is fully documented in the schema with pagination semantics and a note to pass the previous reply's next_page. The description adds no parameter-level detail, so the schema is doing all the work and 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 the specific verb and resource ('List all subscriptions') and enumerates the fields returned, so an agent knows this is a global subscription listing rather than a single-subscription getter. It does not explicitly differentiate itself from siblings like list_customer_subscriptions or list_plan_subscriptions, leaving scope distinctions partly 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?

'List all subscriptions' implies using this tool when an unfiltered list is needed, but there is no explicit when-to-use or when-not-to-use guidance. It never names the customer- or plan-scoped alternatives, so the agent must infer when this global list is preferable.

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 disclose that this is a read-only, idempotent, non-destructive, open-world operation. The description adds useful context about the kinds of line items returned, but it does not elaborate on response shape, pagination behavior, or operational caveats beyond what the schema and annotations provide.

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 compact and front-loaded, first stating what the line items are and then giving the endpoint. There is no redundant or filler text.

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 simple read-only list endpoint with rich schema descriptions and clear annotations, the description is largely complete and explains what the returned line items represent. It could be stronger by explicitly routing the agent away from transfer-level or ledger-level siblings, but no critical calling information is missing.

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 parameters are documented in the schema, including pagination behavior and the transfer token format. The description does not add parameter-level meaning beyond what the schema already provides, so the baseline score of 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?

The description clearly identifies the resource as the ledger line items belonging to a single transfer and gives concrete examples of included item types. It distinguishes this from related transfer tools through the specific line-items scope, though the prose itself does not use an explicit listing verb.

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 description and endpoint path, but there is no explicit guidance on when to choose this tool over `pinpayments_get_transfer`, `pinpayments_list_transfers`, or other ledger-related tools. It lacks when/when-not statements or named alternatives.

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 readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds real value by enumerating the returned fields and stating the page size (25), plus the underlying GET /transfers endpoint, but says nothing about ordering, total counts, or what happens at the last page.

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?

One dense sentence that front-loads the verb, the resource and its disambiguating gloss, then the fields and endpoint. Nothing is redundant or deferrable.

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, listing the returned fields (status, amount, debits/credits, paid_at, reference, line item count, masked bank account, recipient) is exactly the right compensation. Minor gap: no mention of response envelope or pagination termination, though the schema's next_page reference partially covers it.

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 `page` parameter is fully documented in-schema, including the next_page chaining hint. The description repeats the 25-per-page fact but adds nothing new about the parameter, so 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 and even defines the resource semantically ("payouts to bank accounts"), which resolves ambiguity around Paymark-style 'transfers'. It does not distinguish itself from near siblings like search_transfers, list_recipient_transfers or list_transfer_line_items, which is the only thing keeping it off 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?

There is no when-to-use or when-not guidance; the description never says when to prefer search_transfers or list_recipient_transfers over this unfiltered list. The only operational hint, pagination, is implied rather than explained.

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 readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered elsewhere. The description adds useful behavioral detail about which fields free text actually matches (description, email, metadata, cardholder name, currency, amount, tokens), including that amount must be in the currency's base unit, but says nothing about result volume or ordering behavior beyond what the schema states.

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?

One dense sentence with the searchable-field list and endpoint, no filler; the core capability is front-loaded.

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?

All six parameters are optional and fully documented in the schema, and this is a read-only search with no output schema to explain, so the burden is light. What is missing is a note on pagination/result shape, though the page parameter's own description covers next_page.

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 baseline would be 3, but the description genuinely extends 'query: Text to match' by enumerating what text is matched against and clarifying exact-amount matching in base units. Date-range and sort parameters are left entirely to the schema, so it is not a full 5.

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 ('Search charges') and enumerates the matchable fields plus the underlying endpoint GET /charges/search. It distinguishes itself in substance from pinpayments_list_charges by being criteria-driven, but never names that sibling, leaving the distinction 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?

'by free text ... and/or a created-date range' implies the conditions under which this tool applies, but there is no explicit when-not guidance and no mention of pinpayments_list_charges as the unfiltered alternative. An agent must infer the 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds the underlying endpoint and open-world search semantics, but discloses nothing about pagination behaviour, result caps, or what an empty match returns — though the pagination contract is picked up by the schema.

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 core verb is front-loaded, but the second half of the first sentence ('optionally filtered by status') restates the earlier 'by status' and wastes the limited space on redundancy rather than useful differentiation. The trailing endpoint reference is filler for an agent.

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 zero-required-parameter, read-only search with full schema coverage and a strong annotation set, the definition is nearly sufficient — the endpoint, matching fields and filter are present. The only real miss is routing guidance against list_disputes/get_dispute, which for a 35-sibling surface is a meaningful 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 100% and each of the five parameters carries a meaningful description, so the schema does the heavy lifting. The description's mention of status and exact charge token marginally maps to query/status but adds no syntax, format, or matching-rule detail beyond what the schema states.

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 ("Search disputes") and hints at the searchable fields (status, exact charge token), which distinguishes it from the sibling write-free getters. However it never explicitly contrasts with pinpayments_list_disputes, and the phrase 'by status ... optionally filtered by status' is self-duplicating and muddies what is actually being matched.

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 guidance on when to use this versus pinpayments_list_disputes or pinpayments_get_dispute within the large sibling set. The only implicit cue is 'exact charge token', leaving the agent to infer that this is the lookup path for a known charge token rather than a general listing.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered and the description only needs to add operational context. It adds the endpoint (GET /transfers/search) but says nothing about how multiple criteria combine (AND vs OR), whether matching is case-insensitive or substring, or how results are ordered by default — the 'and/or' phrasing actively leaves combination semantics ambiguous.

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 with no filler; the searchable fields and the date-range capability are front-loaded before the endpoint reference. Nothing repeats the annotations 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 a six-parameter, all-optional search with full schema documentation and no output schema, this covers what to search on and the endpoint. The remaining gap is behavioral: how criteria combine and how results are sorted/paginated is left entirely to the schema's per-parameter notes.

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 baseline is 3, but the description genuinely adds meaning the schema lacks: the opaque `query` parameter ('Text to match') is explained as matching token, description, amount or recipient details. It does not clarify the interaction between query and start_date/end_date, but it earns credit above baseline.

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 ('Search transfers') plus the fields the search covers, which is more than a restatement of the name. It does not explicitly contrast itself with the sibling pinpayments_list_transfers, so an agent must infer that search is the criteria-driven path and list is the unfiltered path.

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 'Search transfers by token, description, amount or recipient details and/or a created-date range' — use it when you have match criteria. There is no explicit when-not, no mention of when to prefer pinpayments_list_transfers instead, and no statement about prerequisites or empty-result behavior.

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