Braintree MCP by usefulapi

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

Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds value by disclosing the returned fields (id, legacyId, usage, created-at, detail type) and the natural-language purpose of 'vaulted' payment methods. It does not mention auth scopes or pagination limits, but those are secondary for a read-only list.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three compact sentences: purpose first, then returned fields, then the underlying GraphQL shape. Every sentence contributes information, and nothing is repeated unnecessarily.

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?

Given the simple read-only nature, full schema parameter descriptions, and readOnlyHint annotation, the description is complete. It compensates for the missing output schema by enumerating the returned fields, so an agent knows what to expect. No critical operational detail is absent for correct invocation.

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 fully documented in the schema itself. The description restates 'GraphQL global Customer ID' but adds no new syntax or constraints beyond the schema, and it omits any mention of the `first` pagination parameter. This earns the baseline 3 for high coverage.

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 (List) and resource (vaulted payment methods) scoped to one customer via GraphQL global Customer ID, which clearly differentiates it from sibling tools like find_customer or list_subscriptions. It also names the return fields, making the tool's output predictable.

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?

It supplies clear context: use it for one customer identified by a GraphQL global Customer ID to enumerate that customer's vaulted payment methods. No alternative tool is named, but no sibling performs this exact listing, and the description implies the prerequisite of having a customer ID. The absence of explicit when-not guidance keeps it from a 5.

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

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

readOnlyHint=true already declares the safety profile, and the description adds useful context: this is a single-record fetch keyed by the global ID via the `node` query, returning id, legacyId, name, company, and created-at. It does not mention auth requirements or rate limits, but for a read-only single lookup the disclosure is solid.

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 lookup semantics and return shape come first, then the sibling routing. No filler and nothing repeated from 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?

With no output schema, the description usefully lists the returned fields, and with only one fully-documented parameter and a read-only annotation, nothing an agent needs to call this correctly 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 coverage is 100% and the single parameter already documents that the id is an opaque GraphQL global ID with a note about legacy numeric ids. The description only restates 'GraphQL global Customer ID' without adding format, syntax, or resolution detail beyond the schema, 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 ('Fetch one customer') plus the exact lookup mechanism ('GraphQL global Customer ID via the `node` query') and enumerates the returned fields. It also names the sibling tool it is not, so an agent can distinguish it from braintree_customer_payment_methods without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: use braintree_customer_payment_methods when you also need stored cards/PayPal accounts. This gives a clear alternative with a selecting condition, though it doesn't state when the tool should NOT be used (e.g., for legacy numeric ids, which is only covered in the schema).

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real value beyond that: it discloses the retrieval mechanism (GraphQL `node` query) and enumerates the returned fields, which no structured field provides since 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?

Three short sentences, front-loaded with what it does and which id form is required; every clause 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?

With no output schema, the description compensates by listing the returned fields (amount, status, timestamps, order id, linked customer) and the required id provenance. An agent has everything needed to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single parameter's schema description already explains the opaque base64 form and its origin in a search result's node.id. The description reinforces this but contributes little new syntax or format detail, so the 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+resource ('Fetch one transaction'), names the exact identifier type accepted, and explicitly contrasts it with the short legacy id, distinguishing it from the parallel search tool.

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?

Clearly signals when to use it — when you hold the GraphQL global id from braintree_search_transactions — and warns off the legacy id. It stops short of naming a sibling for the legacy-id path, so the alternative routing is only implied.

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

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

Annotations only declare readOnlyHint=true; the description supplies the non-obvious behavioral truth — GraphQL exposes no native Subscription type, so the tool silently degrades to a customer-scoped TransactionSearchInput, and it cites the upstream issue. That is exactly the kind of behavior an agent could not derive from structured fields, and it does not contradict the read-only annotation.

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 is front-loaded in the first clause, followed by the critical caveat, then the mechanism and the escape hatch. Three dense sentences with little waste, though the TransactionSearchInput detail and the node-field enumeration slightly overlap with 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?

With no output schema, the description carries the return-value burden and does so — telling the agent the response is nodes of transactions and which fields (status/amount/createdAt) to inspect. It also explains the API limitation that shapes the whole tool, so an agent can call and interpret it without outside knowledge.

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?

Both parameters are fully documented in the schema (100% coverage), so the baseline is 3. The description adds context that the underlying semantics are a TransactionSearchInput scoped to the customer, which reframes what customerId actually returns, but it adds no syntax or format detail beyond that.

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 verb and resource ('List a customer's recurring / subscription payment activity') and then crucially corrects the mental model: the tool does not return Subscription objects but customer transactions. This distinguishes it from siblings like braintree_search_transactions, which would otherwise appear identical.

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?

It gives a clear when-to-use ('trace recurring charges' by inspecting status/amount/createdAt) and a when-not-to-use ('for full subscription CRUD use the legacy server SDK / REST API'). It does not, however, explicitly route the agent against the nearest sibling, braintree_search_transactions, leaving the reader to infer the boundary.

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 supply destructiveHint=true, and the description reinforces it while adding genuinely new behavior: the settled/settling precondition, money movement direction, the GraphQL mutation name, and the full-vs-partial refund semantics. It does not mention irreversibility limits, permission requirements, or failure behavior (e.g. refunding an already-refunded charge), which would be the remaining useful context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four compact sentences, front-loaded with the DESTRUCTIVE warning and the eligibility constraint before operational detail. The leading 'DESTRUCTIVE' and the mutation name are mildly redundant with the annotation, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter mutation with no output schema, the description covers everything needed to invoke it correctly: eligibility, argument omission rules, amount format expectation, and the sibling alternative. Return-value detail is unnecessary because no output schema is exposed.

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 the amount format (decimal string) and the 'omit for full refund' rule are already documented in the schema and pattern. The description restates rather than extends 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 (refund a transaction) plus the critical scope constraint: only SETTLED or settling transactions. It names the sibling it must not be confused with (braintree_void_transaction) and the underlying GraphQL mutation, so an agent can select it without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing rules: use this for settled transactions, use braintree_void_transaction for unsettled ones, omit `amount` for full refunds and pass a decimal string for partials. Both the when and the when-not are stated with the alternative named.

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

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

readOnlyHint=true already establishes this as a safe read, so the burden is lower. The description adds genuinely new behavior: it discloses the return shape (id, legacyId, amount, status, createdAt) and the underlying GraphQL `search { transactions }` call. It stops short of explaining pagination/cursor mechanics beyond the word '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?

Three dense sentences with no filler, front-loaded with what is searchable before the implementation and return details. Slightly technical (TransactionSearchInput, GraphQL path) but each 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 read-only search with no output schema, the description supplies the filter model, the returned fields, and the query backing it. The only real gap is pagination behavior when paging past the default 25, which is not addressed.

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 100% schema coverage the baseline is 3, but the description earns extra credit by mapping each visible parameter to the underlying search operator (status `in`, createdAt `greaterThanOrEqualTo`/`lessThanOrEqualTo`, customer.id `is`), clarifying inclusivity and semantics beyond the schema text.

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 (Search) and resource (transactions) plus the three filter axes (date range, status, customer), which separates it from the single-record braintree_find_transaction. It does not name any sibling explicitly, so it stops short of full sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'and/or' signals that filters are optional and composable, which is useful selection context, but there is no explicit when-to-use guidance or routing versus braintree_find_transaction or braintree_list_subscriptions. Usage is only implied.

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 destructiveHint=true, and the description reinforces this with an up-front 'DESTRUCTIVE' marker while adding real value the annotations do not carry: the settlement-state precondition and the required ID form. It stops short of describing irreversibility nuances or failure modes, so not a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three compact sentences, all front-loaded: hazard warning first, then the eligibility condition, then the alternative. 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 one-parameter mutation with destructiveHint coverage and no output schema, the definition supplies everything needed: the safety profile, the precondition, the ID format, and the sibling routing. Nothing required for correct invocation 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 the single parameter is fully documented there; the description's 'Use the GraphQL global transaction ID' only restates the schema's 'GraphQL global transaction ID to void.' Per the baseline rule for high coverage, a 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 (void/cancel a transaction) plus the critical scope constraint (has NOT yet settled), which separates it cleanly from the sibling refund tool. It also names the underlying GraphQL mutation, so an agent knows exactly what operation it is.

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?

Explicitly states both when to use it (unsSettled authorization or submitted-for-settlement transaction) and when not to (already-settled), naming braintree_refund_transaction as the alternative for that case. Nothing is left to inference.

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