braintree_customer_payment_methodsList the vaulted payment methods (credit cards, PayPal accounts, etc.) for one customer, by GraphQL global Customer ID. Returns each method's id, legacyId, usage, created-at, and detail type. GraphQL node { ... on Customer { paymentMethods } }.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | GraphQL global Customer ID (opaque). | |
| first | No | Max payment methods to return. Default 50. |
Changes observed during successful MCP inspections.
Input schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"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.
Add one secure layer between your agents and this server.