braintree

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

The description confirms the read-only nature (consistent with readOnlyHint: true) and adds specifics about the return type (id, legacyId, usage, etc.) and the GraphQL query. No annotations are contradicted. It provides useful behavioral context beyond the annotation alone.

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 sentences, front-loaded with the core action and resource. No extraneous information. Every sentence adds value—purpose, input, output, and underlying query. Highly efficient.

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 list tool with two parameters and no output schema, the description adequately covers purpose, input format, and return structure. It could mention pagination behavior (e.g., 'first' default) and ordering, but overall it's sufficient for an agent to select and invoke 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%: both parameters (id, first) have descriptions in the schema. The description adds minimal extra meaning (e.g., 'GraphQL global Customer ID' is already in schema; 'first' is already described). The description does not significantly enhance understanding 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?

The description clearly states the action ('list'), the resource ('vaulted payment methods... for one customer'), and the input identifier ('GraphQL global Customer ID'). It also specifies the output fields and the underlying GraphQL query, making it easy to distinguish from sibling tools like braintree_find_customer or braintree_list_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?

The description implies usage context (listing payment methods for a customer) but does not explicitly state when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions. The sibling names provide some implicit guidance, but no direct when/when-not guidance 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 declare readOnlyHint=true, consistent with 'fetch'. The description adds context: GraphQL node query, return fields, and important note about legacy numeric IDs needing conversion. No contradictions; description enriches beyond 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 purposeful sentences: first states core functionality and return fields, second provides sibling guidance. No wasted words, front-loaded with key 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 tool with one parameter and no output schema, the description fully covers: purpose, return values, ID type handling, and alternative tool. No 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?

Only one parameter 'id' with rich schema description explaining it's a GraphQL global ID and how to handle legacy IDs. Main description adds 'GraphQL global Customer ID' context. 100% schema coverage means schema already provides detail; description adds slight extra clarity.

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 states the verb 'fetch', the resource 'customer', uses GraphQL node query, and lists return fields (id, legacyId, name, company, created-at). It distinguishes from sibling tool braintree_customer_payment_methods by mentioning that tool for payment methods.

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 tells when to use this tool (fetch basic customer info) and when to use alternative (braintree_customer_payment_methods for payment methods). The instruction on ID type also guides correct usage.

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 description's behavioral disclosure is less critical. However, the description adds value by noting it uses the GraphQL node query and listing return fields (amount, status, timestamps, order id, linked customer), providing useful context beyond the 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?

Two sentences, extremely concise, with the verb and resource first, no wasted words. Every sentence adds value.

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 tool with one parameter and no output schema, the description provides all necessary context: how to identify the transaction (global ID), what the tool does (fetch), and what data is returned (amount, status, etc.). No 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?

Schema already describes the 'id' parameter with 100% coverage. The description adds significant extra meaning: that it's the opaque GraphQL global ID (base64-looking), not the short legacy id, and gives an example of where to get it (from search result's node.id). This exceeds 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?

Description clearly states 'Fetch one transaction' using GraphQL global ID, distinguishes from sibling braintree_search_transactions which returns multiple, and explicitly notes it is NOT the short legacy 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?

Description explicitly says to use the GraphQL global ID from braintree_search_transactions results and warns against using short legacy id. It clearly indicates when to use this tool (when you have a global ID to fetch a single transaction), but does not explicitly state when not to use it.

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

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

Annotations only indicate readOnlyHint=true, but the description reveals critical behavioral details: the tool does not access native Subscription objects but instead returns transactions as a workaround. It also mentions the need to inspect status/amount/createdAt for tracking, adding significant transparency beyond 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?

The description is well-structured with the main purpose first, an important caveat in bold caps for emphasis, followed by explanatory details. While slightly longer, it remains focused and informative without unnecessary fluff.

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 tool's complexity as a workaround for missing GraphQL subscription support, the description adequately explains what it returns (transactions) and how to interpret them. Combined with full schema coverage, it provides sufficient context for an AI agent, though it could mention pagination or error handling.

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?

Input schema covers both parameters with descriptions (100% coverage), so baseline is 3. However, the description adds value by explaining that the 'customerId' scopes a TransactionSearchInput, which is not in the schema, enhancing the understanding of how the parameter is used.

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 states the tool lists a customer's recurring/subscription payment activity, specifying it uses transactions due to API limitations. This distinguishes it from sibling tools like braintree_find_transaction which retrieves a single transaction, making the purpose specific and differentiated.

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 provides clear context on when to use this tool for reading subscription activity via transactions, and advises that full subscription CRUD requires legacy SDK. While it doesn't explicitly list when not to use it, the context is sufficient for an AI agent to infer usage boundaries.

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 indicate destructiveHint=true, and description adds context: it's DESTRUCTIVE, returns money, and is a GraphQL mutation. Full vs partial refund behavior disclosed.

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 concise sentences, each earning its place: flagging destructiveness, core action, alternative, and parameter guidance. Front-loaded and efficient.

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 no output schema, the description covers the mutation's purpose and parameter behavior well. Sibling context and alternative tool named. Slightly less on return format, but adequate.

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 covers both parameters with descriptions. Description adds value by explaining amount omission for full refund and that transactionId is a GraphQL global ID. Baseline 3 due to high coverage, but extra context justifies 4.

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 states the tool refunds a SETTLED transaction using a GraphQL global transaction ID, and distinguishes from voiding unsettled transactions.

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 specifies when to use (settled/settling transactions) and when to use an alternative (braintree_void_transaction for unsettled). Also explains full vs partial refund.

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. The description adds useful behavioral context: it builds a TransactionSearchInput, returns a page of transaction nodes with specific fields, and mentions the underlying GraphQL query. This goes beyond the annotation but does not cover pagination cursors or error handling.

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 concise—three sentences that front-load the core purpose, then detail the search input and return structure. Every sentence adds value without redundancy.

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 tool has 5 parameters, no output schema, and moderate complexity, the description adequately covers the input mechanism and return fields. It lacks details on pagination (beyond 'first' parameter) and error scenarios, but overall it provides sufficient guidance for an agent to use the tool effectively.

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 descriptions for each parameter. The description adds semantic value by explaining the operators for each parameter (e.g., status uses `in`, createdAt uses `greaterThanOrEqualTo`/`lessThanOrEqualTo`). This enhances understanding beyond the schema alone.

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 states the tool searches transactions by date range, status, and customer. It specifies the use of operators (status `in`, createdAt comparisons, customer.id `is`) and differentiates from sibling tools like braintree_find_transaction which retrieves a single transaction.

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 explains how to use the tool (search with filters) but does not explicitly state when to prefer it over alternatives (e.g., braintree_find_transaction for a single transaction) or when not to use it. Usage context is implied but not explicit.

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 indicate destructiveHint=true. The description adds context by labeling 'DESTRUCTIVE', explaining the action (cancel), and highlighting the condition (not yet settled). It also mentions the GraphQL mutation name, which goes beyond 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?

Three sentences, no fluff. Key info (destructive label, condition, alternative tool) is front-loaded and efficiently presented.

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 one required parameter, no output schema, and helpful annotations, the description covers purpose, usage, and behavioral details adequately. It lacks return value description but that is not required.

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 one parameter described. The description repeats 'GraphQL global transaction ID' but adds no extra semantics beyond the schema. 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 states the tool's purpose: to void (cancel) a transaction that has not yet settled. It provides examples (authorization, submitted-for-settlement) and specifies the verb and resource.

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 explicitly tells when to use this tool (for unsettled transactions) and when not (for settled transactions, directing to braintree_refund_transaction instead). It also specifies using the GraphQL global transaction ID.

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