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

Goes well beyond the annotations by disclosing a persistent write, server-side KYC/banking validation that rejects bad routing/account numbers at create time, and the retry/idempotency contract. The idempotency sentence is awkwardly worded ('repeated calls with the same generated key would not duplicate'), which could lead an agent to assume auto-generated keys make blind retries safe; that nuance is worth tightening but is not a contradiction of idempotentHint=true.

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?

Sectioned and front-loaded (definition, USE WHEN, DO NOT USE, SIDE EFFECTS, RETURNS), so an agent can scan to the relevant block. Slightly long, and the idempotency sentence is the one piece of prose that costs more words than it returns in clarity.

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?

Covers the things that matter for a 6-param, nested-object mutation with no output schema: persistence, validation failure modes, the returned id and its downstream use. The remaining gap is the paymentMethod vs defaultPaymentMethod distinction, which the agent must infer from the schema alone.

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; the description adds real meaning by warning that electronicRoutingInfo bank fields are validated and rejected at create time, and by explaining the purpose of idempotencyKey across retries. It does not, however, clarify the relationship between the required paymentMethod and the optional defaultPaymentMethod, which is the one genuine ambiguity left in 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 ('Add a new payment recipient') and immediately disambiguates with a parenthetical definition ('a counterparty you can later send money to via ACH/wire/check'). It also explicitly contrasts with the nearest confusing sibling, mercury_create_customer, so an agent can route correctly without opening a 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 USE WHEN (onboarding vendors/contractors before sending money) and explicit DO NOT USE with the named alternative for the AR-customer case. It also names the downstream consumers (mercury_send_money, mercury_request_send_money) and which field they consume, which is exactly the routing information an agent needs.

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?

Discloses side effects: marks invoice cancelled, stops payment URL, emails customer if previously emailed, logs audit trail, and finality. Complements annotations (destructiveHint=true, openWorldHint=true) with actionable details. 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?

Description is well-organized: action, side effects, usage constraints, and return format. Every sentence adds value without redundancy. 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?

Covers all necessary context: purpose, prerequisites (invoice must be outstanding), side effects, and expected return. No output schema is needed as description provides sample response. Complete for an experienced user.

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?

Single parameter 'invoiceId' with minimal description in schema, but schema coverage is 100%. Description adds no additional semantics beyond stating it's an Invoice ID. Baseline score (3) is appropriate as schema fully describes the parameter.

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 the tool cancels an outstanding invoice, with specific use cases (voiding errors, disputes, re-issuance). Distinct from sibling tools like create or update, and 'DO NOT USE' clause clarifies boundaries.

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 'USE WHEN' and 'DO NOT USE' sections provide clear guidance on appropriate and inappropriate scenarios. Emphasizes user confirmation due to automatic customer notification, which is critical for decision-making.

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 give openWorldHint and destructiveHint=false, so the description carries the real burden: it discloses that this is a persistent write, that it is NOT idempotent at the API level, and that duplicate payloads create two customers. That non-idempotency warning is substantive behavioral context an agent cannot infer from 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?

Labeled sections (USE WHEN / DO NOT USE / SIDE EFFECTS / RETURNS) keep the important constraints front-loaded, and every sentence carries a distinct fact. Length is justified by the duplicate-creation risk it must prevent.

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, and the description compensates by sketching the return shape ({ id, name, email, address, ... }) and telling the agent to retain the id for downstream invoicing tools. With required params, side effects, alternatives, and return value all covered, nothing an agent needs 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%, including the nested address object and its required fields, so the baseline applies. The description adds no field-level meaning beyond confirming the returned id maps to customerId on mercury_create_invoice; it does not clarify why name/email are required or how address 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?

States a specific verb+resource ('Create a new Accounts Receivable customer') and immediately disambiguates the confusing sibling by defining the entity as 'a billable entity you will later invoice' versus a payment recipient. An agent can tell this apart from mercury_add_recipient 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?

Explicit USE WHEN (onboarding a customer before invoicing) and an explicit DO NOT USE that names the alternative tool and explains why the surfaces differ ('outbound bank transfers, not invoicing'). It also prescribes a pre-check against mercury_list_customers to avoid duplicates.

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?

Beyond annotations (non-destructive, idempotent), description adds immediate settlement, no approval workflow, permanent ledger changes, and idempotency details.

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?

Well-structured with clear headings (USE WHEN, DO NOT USE, SIDE EFFECTS, RETURNS). Every sentence adds value, no 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?

Covers purpose, usage, side effects, and return shape. Lacks explicit error handling but sufficient for a well-annotated read/write 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 coverage is 100%, so baseline is 3. Description does not add parameter details beyond schema, but is not required to.

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?

Clearly states the tool moves money between two Mercury accounts owned by the same organization, distinguishes from external transfers and approval-gated requests.

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 provides USE WHEN and DO NOT USE scenarios, names alternative tools (mercury_send_money, mercury_request_send_money), and notes workspace requirement.

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?

Goes well beyond the annotations (openWorldHint, destructiveHint=false): it warns that the write is persistent, that the default SendNow option sends a real email with a payment link (a real-world side effect), and that Mercury Plus / AR write scope is required. It also discloses the API attachment limitation, which annotations do not cover at all.

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?

Sectioned with front-loaded labels (USE WHEN / DO NOT USE / SIDE EFFECTS / RETURNS) and every sentence carries actionable information. No filler despite the length, which is justified by a 16-parameter, email-sending mutation.

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, but the description provides the return shape (id, status, amount, paymentUrl) and explains paymentUrl. Combined with prerequisites, tier requirement and side effects, an agent has everything needed to call this 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%, so the baseline is 3, but the description adds semantics the schema does not: sendEmailOption controls whether a real customer email is sent, and customerId provenance is tied to mercury_create_customer. It doesn't explain destinationAccountId or the other optional fields beyond schema, so not a 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 ('Create a new invoice') and scopes it ('one-shot or to be sent recurrently'), immediately distinguishing it from mercury_update_invoice, mercury_send_money and the customer tools it references. An agent can identify the tool's role 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 USE WHEN and DO NOT USE blocks name the prerequisite (customer must exist, via mercury_create_customer or mercury_list_customers) and route the agent to mercury_create_customer when it does not. It also calls out the attachment workaround, which prevents a failed call attempt.

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?

Describes side effects (persistent writes, non-idempotent) beyond annotations. Does not contradict `destructiveHint=false` (create is additive) and provides context for `openWorldHint=true`.

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?

Structured with clear sections, front-loads action, and every sentence adds value. No wasted words.

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?

Despite no output schema, description provides return structure (`{ id, url, ... }`) and references sibling tools. Covers all critical aspects for agent 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 coverage is 100%; description adds constraints for `url` (public HTTPS, block dangerous IPs) and examples for `events`, supplementing schema descriptions.

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 action ('Register a new webhook endpoint') and the resource (webhook). It specifies that Mercury will POST events, differentiating it from other Mercury 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?

Explicit 'USE WHEN' section defines appropriate scenarios, while 'DO NOT USE' warns against invalid URLs and SSRF risks. Includes guidance on idempotency and preparation.

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?

Description details permanent deletion, loss from AR list, potential dangling customerId on past invoices, and non-recoverability. Annotations already mark destructiveHint and openWorldHint, but description adds concrete repercussions.

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?

Well-structured with labeled sections (USE WHEN, DO NOT USE, SIDE EFFECTS, RETURNS) and bold key terms. Every sentence is informative and no extraneous 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?

For a single-parameter destructive tool with no output schema, the description covers usage, limitations, side effects, and return value. No gaps remain for an agent to safely invoke the 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?

Only one parameter (customerId) is fully described in the schema with format and pattern. The description does not add additional semantics beyond what schema provides. With 100% schema coverage, 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?

The description explicitly states 'Permanently delete an Accounts Receivable customer' with a specific verb and resource. It distinguishes from sibling tools like mercury_create_customer and mercury_update_customer by its destructive nature.

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 clear WHEN to use (removing mistaken or purge-worthy customers) and WHEN NOT to use (if invoices have paid/outstanding status). Also gives an alternative: cancel invoices via mercury_cancel_invoice. Explicitly requires user confirmation.

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 set destructiveHint: true, so the description reinforces this with concrete side effects: permanent deletion, lost delivery history, no replay. This adds valuable context beyond the annotation, though the annotation already signals the core destructive trait.

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 bold headings and bullet points, front-loading the key purpose and destruction warning. While comprehensive, it is not overly verbose and each section adds value, though slightly longer than minimal.

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 appropriately mentions the return payload. It covers purpose, usage side effects, and behavioral expectations comprehensively for a destructive tool with one 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?

The schema already fully describes the single parameter (webhookId) with format and description, so the description doesn't add additional semantic value. It mentions the need for user confirmation but that's a usage guideline, not parameter-specific detail.

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 'Delete a webhook endpoint' and highlights its destructive nature. It distinguishes itself from sibling tools like mercury_update_webhook by emphasizing permanent deletion vs. pausing.

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 when to use (decommissioning webhooks) and when not to (temporary silence), with a clear alternative: use mercury_update_webhook with status 'paused' instead. This provides direct guidance for decision-making.

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?

Description lists return fields and implies read-only, consistent with annotations. Adds expected output structure 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?

Concise, front-loaded with purpose, then usage, then return shape. No wasted words.

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 tool with one parameter and no output schema, the description covers purpose, usage, and return shape completely.

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 with 100% schema coverage; description adds no extra meaning beyond what the schema already 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?

Clearly states the tool retrieves details for a specific Mercury deposit account by ID, and distinguishes from listing 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?

Explicitly tells when to use (when ID known) and when not to use (for enumeration, IO Credit accounts), guiding correct selection.

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 readOnlyHint and openWorldHint; the description adds that it returns full customer detail and gives the return shape. No contradictions.

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?

Highly concise with three clear sections: intro, usage guidance, return shape. No unnecessary words; front-loaded with key info.

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 low complexity, the description adequately covers purpose, usage, and return format. Ellipsis indicates more fields, which is acceptable without output schema.

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 parameter fully with description; description adds context that the ID is already known and that the tool is for lookup, reinforcing the parameter's role.

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?

Clearly states the action (Retrieve) and resource (a specific Accounts Receivable customer by ID). Differentiates from sibling tools like mercury_list_customers and mercury_list_recipients.

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 (when ID is known, faster than listing) and when not to use (enumerating customers or fetching payment recipients). Provides alternative tools.

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 readOnlyHint=true and the description adds specific return fields (line items, status, payment URL). No contradictions; the description enriches the behavioral context 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 concise with three clear sections: main purpose, usage guidance, and return format. Every sentence adds value; no 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?

Despite no output schema, the description lists key return fields, covering what the agent needs. Tool is simple with one parameter; description fully addresses usage and expectations.

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 description for invoiceId. The tool description does not add further parameter semantics beyond what the schema provides, so 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?

The description clearly states 'Retrieve a specific invoice by ID, including line items, status, and the payment URL.' It specifies the verb (retrieve), resource (invoice by ID), and included data, distinguishing from siblings like mercury_list_invoices.

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 includes explicit 'USE WHEN' and 'DO NOT USE' sections, directing to use for fetching one invoice with known ID and avoiding for enumeration or attachments, referencing alternative tools.

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 and openWorldHint, but the description adds substantial non-structured context: the returned downloadUrl is authenticated and requires Bearer token + Accept: application/pdf (not a pre-signed link), and it stays correct under sandbox/proxy hosts. It also discloses the 404 behavior for unissued draft invoices, all well beyond what annotations 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?

Well front-loaded with labeled USE WHEN / AUTH / DO NOT USE / RETURNS sections that each carry actionable content. Slightly long, with a docs URL and URL-template notation that are helpful but marginally verbose; still, few sentences could be cut without losing routing or auth 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?

No output schema exists, but the RETURNS block enumerates the response fields (invoiceId, invoiceNumber, status, slug, downloadUrl), and auth/error behavior for draft invoices is documented. An agent has everything needed to call it and consume the result 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?

Only one parameter (invoiceId), and schema coverage is 100% with the UUID pattern fully documented. The description says the tool fetches the invoice for number/status/slug but adds no format or sourcing detail for invoiceId beyond the schema, so 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: 'Resolve the download URL of an invoice's PDF'. It explicitly names siblings it is not (list_invoice_attachments, list_statements) and explains the derived URL format, so the agent can distinguish it from mercury_get_invoice or mercury_list_invoice_attachments without opening schemas.

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 an explicit USE WHEN block with concrete scenarios (archiving, attaching to email/KYB/compliance), a DO NOT USE block routing to mercury_list_statements and mercury_list_invoice_attachments, and a caveat about draft invoices returning 404. Alternatives are named with the selecting condition.

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 and openWorldHint=true. Description adds behavioral context: returns specific fields, and that the API exposes only one organization per token. No contradictions.

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 with only three short sections. Uses clear headings and bullet-point-like formatting (RETURNS). Every sentence is necessary and informative.

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 no input parameters and no output schema, the description provides a complete overview: what it does, when to use, and the return shape. No gaps for a simple 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?

No parameters in the schema (0 params, 100% coverage). Baseline is 4. Description does not add parameter details because none exist; it correctly states no params needed.

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 ('Retrieve information') and the resource ('Mercury organization'), listing specific fields (legal name, EIN, registered address). It distinguishes from sibling tool mercury_get_account, which is for per-account info.

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 provides USE WHEN and DO NOT USE sections, guiding the agent to use this tool for workspace legal identity and to avoid for per-account info. Mentions no list variant due to API limitation.

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 say readOnly/openWorld; the description adds real behavioral detail beyond that, notably that attachment URLs are stripped from the response and must be fetched via mercury_get_transaction_attachment. That is exactly the kind of hidden-surprise disclosure annotations cannot carry.

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?

Front-loaded verb+resource in the first sentence, then clearly labeled USE WHEN / DO NOT USE / RETURNS blocks. No filler; even the return shape sample earns its place by implying the attachments structure.

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?

There is no output schema, but the description supplies the return shape and explicitly flags the one omitted field (attachment URLs) with the sibling to call instead. Nothing an agent needs to invoke or interpret 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 description coverage is 100% and both parameters are UUIDs documented in the schema, so the baseline is 3. The description only hints at provenance ('typically from mercury_list_transactions') without adding format or constraint detail 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 verb and resource ('Retrieve a specific transaction by ID') plus the scope ('Mercury deposit account'), which lets an agent distinguish it from list_transactions, list_credit_transactions, and get_transaction_attachment without opening a 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 USE WHEN section names the trigger condition (ID already known, typically from mercury_list_transactions) and explains why it beats relisting. DO NOT USE section names both alternatives and when to prefer each, including the client-side filter workaround for IO Credit transactions.

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?

Goes well beyond the readOnlyHint=true annotation by disclosing that the returned URL is an unauthenticated bearer token valid ~12 hours, that it should be treated as a secret, and that pre-fetching mints expiring credentials into logs. This is exactly the kind of non-obvious risk context the description should carry.

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?

Front-loaded with the purpose sentence, then cleanly sectioned into USE WHEN / DO NOT USE / SIDE EFFECTS / RETURNS. Despite its length, every section 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?

No output schema exists, but the RETURNS block supplies the exact response shape ({ transactionId, attachmentCount, attachments: [{ fileName, attachmentType, url }] }), and the security/expiry caveats cover the openWorld risk. An agent has everything needed to call it safely.

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 accountId, transactionId, and fileName are already documented in the schema; the description adds no syntax or format detail. Baseline 3 applies since the schema does the heavy lifting for parameters.

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 (obtain) and resource (pre-signed download URLs for a transaction's receipts/attachments), and distinguishes itself from mercury_list_invoice_attachments and mercury_list_transactions by scoping to a single transaction's attachments.

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 USE WHEN (intending to actually download) and DO NOT USE (just checking whether a receipt exists) sections, plus a named alternative (mercury_list_transactions with hasAttachment: true) for locating candidates and a warning against bulk pre-fetching. 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.

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

Annotations already declare readOnlyHint=true. The description adds the return structure and mentions eligibility, which is helpful but does not contradict annotations. It could expand on openWorld implications, but overall transparent.

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 (4 lines), front-loaded, and every sentence adds value. No wasted words.

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 parameters, a simple return format provided, and annotations covering safety, the description is largely complete. Slight improvement would be noting that workspace-level info is returned, but not essential.

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 has 0 parameters with 100% coverage, so description has no param details needed. Baseline 4 applies as per guidelines for zero-parameter tools.

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 'Retrieve Mercury Treasury account information' and lists specific fields (balance, current yield, eligibility). It distinguishes from sibling tool `mercury_get_account` which is for deposit accounts.

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 provides USE WHEN (checking treasury cash balance or yield, confirming Treasury enabled) and DO NOT USE (for deposit accounts, treasury transactions/statements) with named alternatives (`mercury_get_account`, list tools).

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 readOnlyHint=true; description adds return format details (id, url, status, events) which is consistent and helpful. No contradictions.

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 brief sentences, front-loaded with purpose, no waste. 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 get-by-ID tool, description covers purpose, usage, return structure, and distinctions from siblings. Annotations provide readOnlyHint and openWorldHint. 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 coverage is 100% with parameter description 'The webhook endpoint ID'. Description does not add further parameter semantics beyond schema, so 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?

Clearly states 'Retrieve a specific webhook endpoint by ID', specifying the verb and resource. Distinct from siblings like mercury_list_webhooks which enumerate, and other CRUD operations.

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 when to use (fetch detail of one webhook with known ID) and when not to (use mercury_list_webhooks for enumeration), providing clear alternative.

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 readOnlyHint:true and openWorldHint:true indicate safe read operation and broad scope. Description adds context: returns account details with fields id, name, kind, status, balances, accountNumber, routingNumber, etc., and implies it lists all accounts (no parameters). 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?

Concise, with clear section headers (USE WHEN, DO NOT USE, RETURNS). Every sentence adds value—no redundant or fluff 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?

No output schema, but description fully specifies the return shape with example fields. With zero parameters, all necessary context is covered: purpose, usage, and output format.

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 has zero parameters (100% coverage), so description need not explain parameters. Baseline is 4 per guidelines; description adds no extra param info but reinforces that the tool lists all accounts without filters, which is helpful.

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?

Explicitly states it lists deposit bank accounts (checking, savings, treasury) in Mercury workspace, uses specific verb 'list' and resource, and distinguishes from sibling tools by naming credit accounts and single-account 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 explicit 'USE WHEN' for enumerating before drilling into transactions/balances, and 'DO NOT USE' for IO Credit card accounts (pointing to mercury_list_credit_accounts) or when account ID is known (prefer mercury_get_account). Clear guidance with 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 indicate readOnlyHint=true, confirming no side effects. The description adds value by specifying the return format (cards array with fields like id, last4, type) and noting current API limitations (no card creation/freezing), 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?

The description is concise (4 sentences), well-structured with clear sections (USE WHEN, DO NOT USE, RETURNS), and contains no redundant 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?

Given the low complexity (single parameter, no output schema), the description covers the purpose, usage guidelines, return format, and limitations completely. No additional information is needed for an agent to correctly select and invoke the 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 input schema has 100% coverage for the single parameter accountId, which is clearly documented. The description does not add further semantic meaning beyond the schema, but the schema itself is sufficient.

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 explicitly states it lists physical and virtual cards attached to a Mercury account, with a specific verb and resource. It distinguishes from sibling tools like mercury_list_credit_transactions by exclusion, ensuring no 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?

Clear 'USE WHEN' and 'DO NOT USE' sections provide explicit context for when to use this tool (e.g., spend audits, freezing review) and when not to (e.g., listing credit transactions, which points to an alternative sibling). Also notes API limitations for card creation and freezing.

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 read-only and open world; description adds return format and that category creation is not supported, providing additional 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?

Concise, well-structured with clear sections (USE WHEN, DO NOT USE, RETURNS), no wasted words.

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?

Fully explains purpose, usage, return format, and limitations; no missing context despite no output schema.

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?

No parameters in schema; description does not need to add parameter details. Baseline 4 for zero-param tool.

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 it lists transaction categories, provides examples, and distinguishes from sibling tool mercury_list_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 tells when to use (discovering valid categoryId for update_transaction) and when not to use (listing transactions, category creation), with alternative tool mentioned.

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 readOnlyHint and openWorldHint; description adds endpoint (/credit), return shape, and notes it is a read operation. No contradictions.

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?

Concise and well-structured with sections for USE WHEN, DO NOT USE, RETURNS. 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?

Covers purpose, usage, and return structure adequately. Lacks mention of pagination or limits, but for a zero-parameter list tool with openWorldHint, it is mostly 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?

No parameters, so baseline is 4. Description adds no parameter info, which is acceptable given the parameter count is zero.

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 the tool lists Mercury IO Credit card accounts (charge cards), distinguishes from deposit accounts, and explicitly names the sibling tool for the other account type.

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 explicit USE WHEN (enumerating accounts for balance, statement closing, feeding ID to mercury_list_credit_transactions) and DO NOT USE (deposit accounts, directs to mercury_list_accounts).

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?

Goes well past the readOnlyHint/openWorldHint annotations by disclosing the v1→v2 endpoint 404 behavior, the sign-convention change for statements after 2026-06-15, and the critical operational caveat that downloadUrl is short-lived. These are non-obvious traits an agent could not get from structured fields.

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?

Front-loads the core action, then uses labeled USE WHEN / DO NOT USE / RETURNS blocks so an agent can scan to the needed section. The changelog sentence is unusual in length but earns its place by preventing misread amounts.

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 supplies the return shape itself, including the statement fields and downloadUrl. Combined with the endpoint caveat and sibling routing, an agent has everything needed to call this correctly on the first attempt.

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 accountId parameter is already documented as coming from mercury_list_credit_accounts. The description reinforces that it must be an IO Credit account, but adds no format or sourcing detail beyond the schema, 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 ("list monthly statements for a Mercury IO Credit card account") and immediately distinguishes itself from mercury_list_statements and mercury_list_treasury_statements. An agent can identify the correct tool without opening any 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 USE WHEN block names the concrete scenarios (accounting, audit, CPA) and the DO NOT USE block names the two sibling alternatives plus the excluded resource types. Nothing about tool selection 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.

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

Annotations only declare readOnlyHint/openWorldHint, so the description carries the real burden and does: it discloses Mercury's silent truncation when `start` is omitted, with a quantified observation (68 vs 532 rows) to make the risk credible, and prescribes offset paging until fewer than `limit` rows return. It also flags that receipt URLs are stripped and must be fetched via `mercury_get_transaction_attachment`. Slight deduction for not stating rate limits or the truncation window's exact boundary.

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?

Front-loaded purpose, then uppercase USE WHEN / DO NOT USE headers, then a clearly marked warning, then RETURNS. Long but every block is functional — the anecdotal row counts exist to justify the truncation warning rather than pad the 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?

No output schema exists, and the description compensates by sketching the returns envelope, explaining that `pending` items are reversible authorisations, and noting `hasAttachment` is always present as a receipt-gap signal. For an 8-parameter, single-required-param read tool with annotations, nothing an agent needs to call it 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%, so baseline is 3, and the description still adds value the schema cannot: the semantics of omitting `start`, how `offset` should be used with `limit`, and what `detail: "compact"` vs `"full"` actually yields. It does not restate or clarify `search`, `end`, or `accountId` beyond 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 and resource (list transactions on a Mercury IO Credit card account) plus the distinguishing scope detail that it includes pending, not-yet-settled authorisations. It names the confusable sibling `mercury_list_transactions` and explains that both hit the same endpoint, so an agent can separate the two without reading 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?

Has an explicit USE WHEN block (auditing card spend, reconciling a statement, building a card-level view) and an explicit DO NOT USE block routing deposit-account work to `mercury_list_transactions`. It also gives a concrete downstream filter recipe (`status: "sent"` for posted-only), leaving nothing 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 and openWorldHint=true. The description adds cursor-based pagination details ('Use startAfter / endBefore for paging beyond the limit') and return format, enhancing 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 concise (5 sentences) with clear sections: purpose, USE WHEN, DO NOT USE, RETURNS. Front-loaded with purpose, no redundant 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?

Given the tool's simplicity (list with pagination), annotations, and schema, the description covers usage context, pagination, and return structure. Output schema is not provided, but description specifies return format. Complete for a list endpoint.

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 75%, with parameter descriptions for limit, startAfter, and endBefore. The description adds context on how to use pagination cursors ('Use startAfter / endBefore for paging'), but does not document the 'order' parameter, which is not described in schema either.

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 'List Accounts Receivable customers, with cursor-based pagination.' It provides a specific verb ('list'), resource ('AR customers'), and mentions pagination. It distinguishes from siblings like 'mercury_list_recipients' and 'mercury_get_customer'.

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 when to use ('enumerating AR customers before creating an invoice...or for a customer-level audit'), when not to use ('DO NOT USE: for payment recipients'), and provides alternatives ('mercury_list_recipients', 'mercury_get_customer').

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 readOnlyHint=true. The description adds critical behavioral details: download URLs are short-lived requiring refetch before download, and it returns a specific structure. 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?

The description is concise (three sections: what, use when, do not use, returns) with no redundant sentences. 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?

Given a single parameter, no output schema, and annotations providing safety hints, the description is complete. It includes return format and critical usage notes, leaving no ambiguity for agent 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?

The input schema has 100% coverage with a description for invoiceId. The description adds no extra semantic value beyond what the schema provides, but the parameter is simple and well-documented; 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?

The description clearly states it lists attachments associated with an invoice, specifying types (PDF copies, supporting documents). The use case section further clarifies purpose, and it is distinct from sibling tools like mercury_get_invoice or mercury_create_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?

Explicitly provides USE WHEN and DO NOT USE guidance, including alternatives (upload is not supported) and a note on short-lived download URLs. This helps the agent decide when to invoke and when not.

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 (readOnlyHint=true) already indicate safety; description adds pagination behavior (cursor-based) and return structure, but no additional behavioral traits beyond that.

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?

Concise, front-loaded with purpose, and structured with usage guidelines and return info; no unnecessary words.

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?

Despite no output schema, the description provides a clear return structure and pagination details, making it complete for a list 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 coverage is 100%, so the description's extra notes on pagination and defaults add minimal value beyond what's already in 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 'List invoices in your Mercury workspace' with specific verb and resource, and distinguishes from siblings like mercury_get_invoice and mercury_list_invoice_attachments.

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 provides 'USE WHEN' scenarios and 'DO NOT USE' with an alternative (mercury_get_invoice), as well as mentions current API limitations on filtering.

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 and openWorldHint. The description adds the return format structure but no additional behavioral traits. No contradictions.

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?

Concise: three clear sections (purpose, usage, returns). 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?

With 0 parameters and no output schema, the description covers purpose, usage guidelines, and return format thoroughly. No gaps for this tool's complexity.

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 has 0 parameters, so schema coverage is 100%. Description adds context about what recipients are and their fields, which is helpful 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 it lists all payment recipients for outbound ACH/wire/check in the workspace, with a specific verb and resource, and differentiates from sibling tools like mercury_list_customers.

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 (before sending money, to get recipientId for mercury_send_money) and when not to use (for AR customers, directing to mercury_list_customers), with clear 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 cover read-only/open-world, but the description adds critical time-sensitive behavior: PDF URL is short-lived and must be re-fetched before download. Also explains the v1/v2 endpoint failure mode.

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?

Structured with USE WHEN, DO NOT USE, RETURNS sections; every sentence adds operational 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?

Covers purpose, alternatives, critical failure routing, return shape, and URL lifetime. Complete for the 3-param tool despite no output schema.

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. Description doesn't explain start/end semantics beyond schema, but it names the account scope and implies accountId requirement.

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?

Specifies verb (List), resource (monthly statements), and scope (Mercury deposit account). Explicitly distinguishes deposit statements from credit and treasury statements.

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 explicit USE WHEN examples and DO NOT USE routing to the two sibling alternatives with a reason (v1 404 for credit).

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?

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses that omitting `start` silently truncates to a recent window with no response signal, gives a concrete observed 60-vs-391 data point, prescribes offset paging until a short page, and explains that attachment URLs are deliberately stripped because they are 12-hour bearer credentials. That is exactly the kind of hidden behavior annotations cannot convey. It stops short of 5 only because it does not state auth/permission requirements 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?

Front-loaded with the one-line purpose, then clearly sectioned USE WHEN / warning / DO NOT USE / RETURNS. Every sentence carries operational weight — the truncation warning, sibling redirects, and receipt-URL rationale all change agent behavior; 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?

With no output schema, the description compensates by sketching the compact response shape and confirming `hasAttachment` is always present, plus where receipt URLs must be fetched instead. Adequate for an 8-parameter read tool; only minor gaps remain (error behavior, exact default window boundary).

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 the baseline would be 3, but the description adds semantics the schema lacks: the trap that `start` is effectively required for a bounded audit, that `offset` must be used to page past `limit`, which filters run server-side, and what `detail: "compact"` vs `"full"` actually changes in the payload. This materially changes how the parameters must be set.

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 transactions for a Mercury deposit account) and immediately names the account surface it covers. It explicitly disambiguates from the two nearest siblings, mercury_list_credit_transactions and mercury_list_treasury_transactions, so an agent can route correctly without opening schemas.

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 explicit USE WHEN scenarios (auditing, reconciliation, ledger view) and an explicit DO NOT USE section naming the alternative tools for the cases it does not cover. Nothing about tool selection 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.

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond them: the PDF downloadUrl is short-lived and must be fetched shortly before download. It does not mention ordering, pagination, or how far back statements go, which keeps it from 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?

Front-loaded purpose sentence followed by labeled USE WHEN / DO NOT USE / RETURNS blocks, each carrying distinct information. There is no filler or repetition of the schema, and the time-sensitivity caveat sits next to the use case it affects.

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 tool with no output schema, the definition supplies everything needed: intent, exclusions, the known failure mode (expired URL), and an inline sketch of the return shape. Nothing an agent needs in order to call it 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?

Only one parameter and schema description coverage is 100% with the field documented as 'Treasury account ID', so the schema already carries the semantics. The description's phrase 'for a Mercury Treasury account' merely echoes that; no format or source-of-ID guidance is added. 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 monthly statements for a Mercury Treasury account') and immediately scopes it to Treasury, which separates it from the deposit-account and credit-card statement siblings. An agent can classify this tool from the first sentence alone.

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 USE WHEN clause names the concrete intent (fetching a past statement URL for tax/audit export), and the DO NOT USE clause routes to the two named alternatives, `mercury_list_statements` and `mercury_list_credit_statements`. No inference is required.

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 cover only readOnlyHint/openWorldHint; the description adds non-obvious behavior the agent could not otherwise know: no start/end date filter exists, so period audits require client-side filtering on canonicalDay, and cursor pagination must be followed until null rather than inferred from a short page. It even warns that an offset argument is silently ignored and causes page-1 re-reads — precisely the kind of failure mode that prevents wrong calls.

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?

Well front-loaded with labeled blocks (USE WHEN / DO NOT USE / warnings / RETURNS), and every section carries load-bearing information. Slightly verbose where the DO NOT USE routing and the 'use mercury_list_transactions instead' warning restate the same contrast, but nothing is 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?

There is no output schema, and the description compensates with an explicit RETURNS block naming the shape, the compact-vs-full distinction, and null-field omission. Combined with the date-filter and pagination caveats, an agent has everything needed to call and page this tool 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%, so the baseline is 3; the description still adds real semantics beyond the schema by specifying the pagination termination condition and the practical consequence of the missing date parameters. It stops short of 5 because it does not elaborate on `limit`/`order` or the `detail: "full"` field set beyond a one-liner.

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?

Opens with a specific verb+resource ('List transactions for a Mercury Treasury account') and names the row types (sweeps, dividend accruals) so the agent knows exactly what is returned. It also explicitly separates itself from mercury_list_transactions and mercury_list_credit_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?

Provides an explicit USE WHEN block (auditing cash flows, reconciling yield accruals, Treasury-only ledger) and a DO NOT USE block that routes to the two competing siblings by name. The routing decision is fully determined without opening any other 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 provide readOnlyHint and openWorldHint. Description adds context about the return structure and clarifies that webhook delivery history is not accessible via API, going beyond what annotations 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?

Three concise paragraphs with clear headings (USE WHEN, DO NOT USE, RETURNS). Every sentence is informative and necessary.

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 parameter-less tool with no output schema, the description fully covers purpose, usage, and return structure. No gaps remain.

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?

No parameters exist, so the description does not need to elaborate. It adds value by specifying the return format, which compensates for the lack of an output 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 'List all webhook endpoints' with a specific verb and resource. It distinguishes this tool from siblings like get, create, delete, and update webhooks.

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?

Includes explicit 'USE WHEN' and 'DO NOT USE' sections, providing concrete scenarios (audit, finding ID before update/delete, etc.) and excluding delivery history, which only the dashboard provides.

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 description discloses that the tool always creates a pending approval request regardless of workspace policy, that no money moves until human approval, and that it is idempotent via idempotencyKey. This adds significant context beyond annotations (destructiveHint, idempotentHint, openWorldHint) and aligns with them without 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?

The description is well-structured with clear sections (overview, USE WHEN, DO NOT USE, SIDE EFFECTS, RETURNS). Each sentence is informative and concise, with no redundant or wasted words.

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 7 parameters and no output schema, the description provides complete context: it explains the approval workflow, idempotency mechanism, return shape, and references sibling tools. The description is sufficient for an agent to understand and invoke the tool 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 schema provides descriptions for 5 of 7 parameters (71% coverage). The description adds only a note about idempotencyKey auto-generation and retries, which is already covered in the schema. No additional parameter details are provided, so 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 tool is for 'Request to send money' and emphasizes it creates a pending approval request. It distinguishes from sibling tools like mercury_send_money (immediate execution) and mercury_create_internal_transfer (internal transfers), making purpose 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 explicitly states when to use (submitting outbound payments that always wait for human sign-off) and when not to use (internal transfers or immediate payments), and names the alternative tools. This provides clear guidance for tool selection.

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?

Discloses real money movement, irreversibility of wires, dependence on workspace approval policy, idempotency via idempotencyKey, and audit logging. Aligns with annotations (destructiveHint, idempotentHint) and adds significant context beyond them.

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?

Well-structured with bold headings and front-loaded purpose. While comprehensive, a few sentences could be tightened, but no extraneous information. Earns its length.

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?

Despite lacking an output schema, the description adequately explains return values and status. Covers side effects, approval policies, and practical usage constraints. Fully sufficient for a high-impact financial transaction 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 coverage is 100% with detailed descriptions for all 7 parameters. The description adds minor context (e.g., idempotencyKey auto-generation) but does not significantly extend beyond the schema. Baseline score 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 explicitly states 'Send money from a Mercury account to an external recipient via ACH, wire, or check', providing a specific verb and resource. It also distinguishes from siblings by naming alternatives for internal transfers and always-review payments.

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?

Clear guidance on when to use (paying an existing recipient) and when not to (internal transfers, always-review payments) with named alternatives. Explicitly advises confirming details with the user before calling.

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 destructiveHint=false and openWorldHint=true, so the description carries the real burden and does: it discloses that the write is persistent, that omitted fields retain current values, and that existing invoices are not retroactively modified. Those are precisely the non-obvious mutation semantics an agent needs and go well beyond the annotation set.

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 labeled blocks (statement, USE WHEN, DO NOT USE, SIDE EFFECTS, RETURNS), each one or two sentences, with the core action front-loaded. No sentence is 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?

No output schema exists, so the description supplies the return shape ({ id, name, email, address, ... }), adds mutation/persistence semantics, and covers sibling routing. For a 4-parameter nested-object update tool, nothing an agent needs to call it 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 only 50%, so the description must compensate, and it partly does: it names the updatable surface (name, email, billing address) and the critical partial-update rule that only passed fields change. It does not explain the required customerId or the nested address requirements, but the schema's own nested descriptions cover country code and recipient name, so the gap is modest.

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 ('Update an existing Accounts Receivable customer') and immediately scopes it with 'Pass only the fields you want to change.' It also names the sibling it is not (mercury_delete_customer) and rules out the invoice-change interpretation, so an agent can distinguish it from create/delete/update_invoice without opening a 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?

An explicit USE WHEN block names the amendment scenarios (contact details, billing address) and an explicit DO NOT USE block routes deletes to mercury_delete_customer and invoice reassignment to cancel + recreate. When-to-use, when-not, and alternatives are all 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?

Goes well past the annotations (destructiveHint=false, openWorldHint=true) by disclosing the hidden full-payload/merge behavior, that the customer-facing payment URL is unchanged, and critically that the customer is NOT re-notified after an emailed invoice is amended. Overwrite here is field-scoped merging, so it does not contradict destructiveHint=false.

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?

Labeled sections (USE WHEN / DO NOT USE / SIDE EFFECTS / RETURNS) with the core behavior front-loaded in the first sentence. Length is justified because each block delivers a distinct, actionable fact.

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?

Despite no output schema, it sketches the return shape ({ id, status, amount, ... }) and covers the mutation lifecycle concerns an agent needs: merge behavior, irreversibility of paid-invoice edits, and the absent customer notification. Nothing essential 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?

With only 33% schema description coverage, the description compensates by enumerating the commonly-changed fields (line items, due date, memo, PO number) and by making the partial-update contract explicit, which is the key semantic for this tool. A few parameters (ccEmails, invoiceNumber, internalNote, invoiceDate) still get no meaning from either source.

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 ("Update an existing invoice") and immediately clarifies partial-update semantics with "Pass only the fields you want to change." It is unmistakably distinct from mercury_create_invoice, mercury_cancel_invoice and mercury_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?

Explicit USE WHEN condition (amending an outstanding invoice before payment) and DO NOT USE block that routes to mercury_cancel_invoice for cancellation and to cancel+recreate for customer/destination changes. It even names a precondition check (fetch first to confirm status) for paid invoices.

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 cover destructiveHint=false and openWorldHint=true; the description adds the persistence of the write, the partial-patch semantics ('only the fields you pass are changed'), and a Mercury-side security constraint that forces recreation for banking changes. The singular-vs-plural endpoint warning is an unusual but real implementation gotcha worth disclosing.

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?

Labeled sections (USE WHEN / DO NOT USE / SIDE EFFECTS / RETURNS) with the purpose statement front-loaded. No filler; each block carries decision-relevant 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?

No output schema exists, and the description compensates with an explicit RETURNS shape. Together with the side-effect and exclusion notes, an agent has everything needed to call this correctly for a 6-parameter mutation 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 coverage is 83%, so the schema already documents most parameters and the baseline is 3. The description adds the meaningful semantic that this is a partial update — unspecified fields are left untouched — which changes how an agent should populate the optional params, plus the intent behind defaultPaymentMethod changes.

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 (update an existing payment recipient) and immediately enumerates the mutable fields. The DO NOT USE section names mercury_add_recipient, so an agent can distinguish the two 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?

Explicit USE WHEN, DO NOT USE, and named alternative routing: changing bank/routing numbers must go through mercury_add_recipient. The motivating example (ACH → wire re-routing without recreating) makes the selection condition concrete.

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 cover destructiveHint=false and openWorldHint=true, so the description adds substantial value: persistent overwrite on Mercury's side, audit-log recording, no effect on the booked transaction or counterparty. Missing rate-limit/auth notes, but the mutation semantics are well disclosed and consistent 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?

Labeled sections (USE WHEN / DO NOT USE / SIDE EFFECTS / RETURNS) with the core purpose front-loaded. Every sentence carries information an agent would otherwise have to guess.

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 supplies the return shape, the attachment-URL stripping caveat with a pointer to the right sibling, the underlying endpoint, and immutability constraints. Nothing needed to call it 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 every parameter's description already documents the null-vs-omit semantics, so the description's 'Send `null` to clear a field, omit the key to keep the current value' largely restates structured data. It adds marginal framing but no new syntax or constraints 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 verb and resource ('Update a transaction's internal note or category') and immediately bounds the scope with '(no money movement)'. This cleanly distinguishes it from amount/counterparty/status mutations the agent might otherwise attempt.

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 USE WHEN and DO NOT USE sections, including the alternative path for attachment downloads ('use mercury_get_transaction_attachment'). The exclusion of amount/counterparty/status changes is exactly the disambiguation an agent needs.

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 description discloses side effects: overwrites the webhook record, persistent changes, immediate effect of new URL, and resumption of delivery if status becomes active. This adds detail beyond the annotations (destructiveHint=false, openWorldHint=true), which only hint at safety and side effects.

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, using structured labels (USE WHEN, DO NOT USE, SIDE EFFECTS, RETURNS) to organize information efficiently. No superfluous sentences; each section adds clear 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?

Despite no output schema, the description explicitly states the return format as '{ id, url, status, events, ... }'. It covers all relevant aspects for an agent to use the tool correctly: when to use, side effects, parameter semantics, and return values.

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?

All parameters have descriptions in the schema (100% coverage), and the description adds value by providing concrete examples for eventTypes, clarifying status effects (reactivation), and reiterating security rules for url. This goes beyond the schema's basic type/format info.

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 explicitly states 'Update an existing webhook endpoint (URL, status, or subscribed events)', using a clear verb+resource structure. It distinguishes itself from sibling tools like mercury_create_webhook and mercury_delete_webhook by focusing on updates.

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 includes 'USE WHEN' and 'DO NOT USE' sections, providing explicit guidance on appropriate contexts (e.g., rotating URL, reactivating after failures) and exclusions (e.g., inspecting delivery history). It also references sibling behavior for SSRF guard.

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