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

Beyond the annotations, the description discloses substantial behavioral constraints: only safe relative /v2/ or /v3/ paths are accepted, only GET/POST/PUT methods, absolute URLs are blocked to prevent credential exfiltration, and POST/PUT require confirm=true. These align with (and add detail to) the destructiveHint=true annotation; no contradiction.

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

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

Four short sentences, each earning its place: purpose first, then method/path constraints, then the safety rationale, then the mutation gate. No filler or 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?

With an output schema present, return values need no explanation, and the annotations plus description cover the safety profile well. The remaining gaps are body format and idempotencyKey usage guidance, which an agent needs for correct POST/PUT invocations, but the core contract is otherwise fully specified.

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

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

Schema coverage is only 40%, so the description carries part of the burden. It adds real value for path (relative-only, absolute URLs blocked) and reinforces the confirm gate, but it leaves body format and idempotencyKey semantics completely unexplained — meaningful gaps for a generic request tool. The POST/PUT confirm requirement merely restates the schema's confirm description.

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 purpose — an escape hatch for documented MyFatoorah v2/v3 endpoints — and explicitly scopes it to endpoints 'not covered by another tool,' which differentiates it from the six sibling tools that cover specific payment/invoice/refund operations. The resource (MyFatoorah API endpoints) and scope (only uncovered endpoints) are unambiguous.

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

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

The description gives a clear selection criterion: use this tool only when a documented endpoint is not covered by another tool. This implies sibling tools should be preferred for their respective operations, though it does not name them explicitly or give a when-not-to-use example.

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 that this is not read-only and not idempotent; the description adds the crucial consequence that in live environments it creates a real payable invoice, and the PaymentURL is the customer-facing payment destination. This is exactly the kind of real-world context needed for a financial write operation, and there is no contradiction with 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?

Four short sentences, each contributes a distinct fact: endpoint, live consequence, key parameter behaviors, and result URL. No filler and purpose 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?

For a complex 15-parameter financial tool, the description supplies the essential operational context: live invoice risk, payment-method behavior, invoicing mode, and customer payment URL. The schema and output schema cover most parameter and return details, so the remaining gaps around idempotency and sandbox behavior are not fatal.

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

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

Schema description coverage is only 47%, so the description should compensate for under-documented parameters. It does add useful meaning for paymentMethod (omit to show enabled methods) and notificationOption (invoicing), but other fields like idempotencyKey, suppliers, and displayPaymentMethods receive no extra explanation, leaving gaps.

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 opens with a specific verb ('Creates') and resource ('payment/invoice') plus the exact endpoint POST /v3/payments. It also states the key outcome ('real payable invoice' in live, PaymentURL for customer), which clearly distinguishes it from the get/refund sibling tools.

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

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

It gives clear operational guidance: omit paymentMethod to surface all enabled methods, and use notificationOption for invoicing. The live-environment warning frames when the call has real financial effect, though it does not explicitly name sibling alternatives, so it stops short of 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?

Annotations already mark destructiveHint=true/readOnlyHint=false, but the description adds non-redundant context: the refund is 'real', moves money in live environments, and requires explicit user approval of exact PaymentId and amount. No contradiction with 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 sentences: the first states the action and risk, the second provides the mandatory approval guard. There is no filler or redundant restatement of schema content.

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

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

Given the output schema and destructive annotations, the description covers the essentials: what it does, that it moves real money, and the safety precondition. It could additionally mention duplicate/retry behavior since idempotentHint=false, but for a refund creation call this is a minor gap.

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

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

Schema description coverage is only 13%, so the description must compensate. It adds meaning for the required parameters: 'full or partial' explains amount and 'confirm must be true' restates the approval gate. However, it does not help with the five optional parameters such as idempotencyKey, supplierRefundedAmount, or serviceChargeOnCustomer, so compensation is incomplete.

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 it creates a real full or partial refund via POST /v3/refunds, a specific verb+resource that is clearly distinct from create_payment and get_refund among siblings. 'Moves money in live environments' reinforces what operation this 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?

Gives an explicit call condition ('only after the user explicitly approves the exact PaymentId and amount; confirm must be true'), which tells an agent when it is safe to invoke a destructive refund. It does not name sibling alternatives such as get_refund for verification, so it lacks explicit exclusions or alternative routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral detail beyond that, particularly the exact endpoint routing and the fact that external identifier lookup returns the most recent matching invoice. No contradiction with 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 sentences with no filler. The purpose is front-loaded, and each clause carries distinct information: the lookup constraint, the invoice-ID path, and the external-identifier path with its recency behavior.

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 has only two parameters, an output schema, and annotations covering safety and idempotence. The description provides the remaining necessary operational details, including endpoints and the semantics of external identifier lookups, so 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 description coverage is only 50%, with lookupBy having no description beyond its enum. The description compensates by mapping lookupBy values to specific endpoint paths and clarifying that externalIdentifier resolves to the most recent matching invoice, adding 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?

The description states a specific action, 'Gets an invoice', and precisely defines the two lookup modes with endpoint paths. The resource (invoice) is clearly distinct from sibling tools that retrieve payments, refunds, or payment methods, so an agent can select it without ambiguity.

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 clearly conveys when this tool is appropriate: when an invoice needs to be retrieved by exactly one lookup type. It does not explicitly name alternatives or exclusion conditions, but the sibling tools are organized by resource, making the intended context evident.

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. The description adds valuable behavioral context beyond annotations: it is authoritative, uses a specific GET endpoint, and defines the exact success criteria (Invoice.Status = PAID and Transaction.Status = SUCCESS). No contradiction with 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 concise sentences with no filler. The first sentence front-loads the action, resource, and endpoint, while the second delivers the critical success rule. Every sentence earns 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?

The tool is simple with a single parameter, high schema coverage, rich annotations, and an output schema. The description covers the essential success logic and authoritative nature, making it complete enough for correct invocation. It could be slightly stronger with an explicit pointer to sibling tools, but this is not essential for a read-only getter.

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 paymentId documented as 'PaymentId from a callback or payment response.' The description mentions 'by PaymentId' but adds no additional semantic detail beyond what the schema provides, so it meets the baseline without exceeding 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?

Description states a specific verb ('Gets'), resource ('payment details'), and identifier ('PaymentId'), with a direct API endpoint. It is distinct from siblings by focusing on payment details, but it does not explicitly differentiate itself from myfatoorah_get_invoice, which could be confused for a closely related 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 description implies usage: use this tool when you have a PaymentId and need authoritative payment details, especially to verify success. However, it gives no explicit guidance on when to prefer this over siblings like myfatoorah_get_invoice or myfatoorah_api_request, nor any exclusions.

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 read-only, idempotent, open-world, and non-destructive behavior. The description adds value by scoping results to the current account and by disclosing that the output contains an ApiName field that must be reused. This is useful behavioral context beyond what 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?

Two tight sentences with no filler. The first states the core action and scope; the second provides a concrete next step. Every word earns its place and the key information 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?

For a zero-parameter read-only listing tool with a full output schema and extensive annotations, the description covers the action, the account scoping, and the downstream usage of the result. Nothing critical is missing for an agent 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?

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameter semantics, and the schema coverage is 100% by definition.

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 payment methods enabled for this account.' This clearly distinguishes it from the create/get/refund siblings, and the second sentence explains how the result is used downstream.

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 gives clear contextual guidance: call this to discover payment methods, then read ApiName and pass it as paymentMethod when creating a hosted payment. It does not explicitly list exclusions or alternative tools, but the workflow context is sufficient given the sibling operations are quite different.

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 convey read-only, idempotent, non-destructive behavior. The description adds meaningful context beyond those hints by naming the HTTP endpoint and listing possible refund statuses (Refunded, Canceled, Pending), which helps the agent interpret results. No contradiction with 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 sentences with no filler: the first front-loads the action and endpoint, the second adds useful status context. Every word earns 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?

The tool is a simple read operation, annotations cover safety, and an output schema exists so return-value documentation is unnecessary. The description is complete enough for correct invocation; only usage-vs-alternatives context is lightly 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 0%, so the description must compensate. It does so by identifying refundId as the RefundId used for lookup and tying it to the URL path. For a single, self-named parameter this is sufficient additional meaning beyond the raw 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 states a specific verb ('Gets'), the resource (a refund), the lookup key (RefundId), and the exact endpoint (GET /v3/refunds/{refundId}). This clearly distinguishes it from sibling tools like myfatoorah_get_payment and myfatoorah_get_invoice.

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

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

The description implies the tool is used when you have a RefundId and need refund details, but it does not explicitly discuss when to prefer this over sibling tools such as myfatoorah_get_payment, myfatoorah_get_invoice, or myfatoorah_create_refund. No exclusions or alternatives are named.

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