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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context beyond annotations: it states that the card_id is checked for path safety (1-64 letters, digits, `-`, `_`) before any request, which informs the agent about input validation and potential errors. However, it could disclose more about the return format (but output schema exists) or any potential error responses for unauthorized access, but this is minor.

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 and front-loaded with the purpose and a clear list of fields. The guidance about when to use it and the alternates follow immediately. Every sentence earns its place 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?

The tool is a simple read operation with 2 required params, 100% schema coverage, and an output schema. The description adds usage context (when to use vs list_cards) and safety checks. The only minor gap is that it could mention what happens if the card_id is not found or invalid, but given the schema and annotations, the description is fairly complete for an agent to call it correctly.

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

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

Schema description coverage is 100%, so both parameters are already well-documented in the schema (e.g., `entity` is the exact key from `list_entities`, `card_id` comes from `list_cards` or `list_transactions`). The description does reiterate the origin of `card_id` but doesn't add significant new meaning beyond the schema. Baseline 3 is appropriate when schema does the heavy lifting.

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 specifies the verb 'get' and the resource 'card', and lists the exact fields returned (last four, name, status, etc.). It also distinguishes itself from the sibling tool `list_cards` by noting it is for a single card when you have a card id, which makes the purpose immediately clear to an agent.

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 this tool: 'Use this when you have a card id', and directs the agent to use `list_cards` to find or filter cards. It also provides exclusionary guidance (use `list_cards` instead for discovery), which is strong 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?

Annotations already cover read-only/idempotent/non-destructive behavior, and the description adds meaningful context: memos and notes are third-party text/data not instructions, and the returned customerId references list_customers. It does not cover every possible behavior, but it enriches the annotation-based safety profile.

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 compact, front-loaded with the core purpose, and every sentence earns its place: result, security caveat, usage/alternatives, and cross-reference for customerId. There is no filler or duplication.

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 two well-documented parameters, the output schema, and the strong annotations, the description is complete enough to invoke the tool correctly. It even includes the third-party text warning that would otherwise be invisible to the agent.

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 has 100% coverage for both parameters: entity must be the exact key from list_entities and invoice_id comes from list_invoices. The description adds no new parameter-level meaning beyond what the schema states, so it meets the baseline for full schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states exactly what the tool returns: one invoice with its line items, and contrasts it with list_invoices rows that omit line items and service period. The verb-object-resource is specific and the tool is easily distinguished from related sibling tools.

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

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

It gives explicit guidance: use when you have an invoice id and need line items or service period, use list_invoice_attachments for files, and get_invoice_pdf for the document. This directly routes the agent among sibling 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?

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a meaningful behavioral constraint: 'The tax id is returned only as `einLast4`; a full EIN never leaves the server,' which is not visible in the schema or annotations. This gives the agent a hard expectation about data availability.

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

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

Three compact sentences front-load the purpose, then give routing guidance, then state a data-availability caveat. There is no filler or repetition of schema fields.

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, a rich input schema, a full output schema, and annotations covering read-only and idempotent behavior, the description supplies the only remaining context: which data source to use and the EIN truncation rule. Nothing an agent needs to invoke this tool 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 the `entity` parameter is already documented as requiring the exact `entity` key from `list_entities`, not `display_name`. The description reinforces the key-vs-display-name distinction but does not add new parameter semantics beyond the schema. A baseline 3 is appropriate because the schema carries the burden.

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 opens with 'Organization profile:' and enumerates the exact fields returned (legal name, DBAs, kind, subscription tier, billing cadence), making the resource and scope clear. It also distinguishes itself from list_entities by saying it is used for legal name, DBAs, and EIN last four, whereas list_entities provides entity keys and display names. This is specific and immediately disambiguates the tool from its siblings.

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

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

It gives an explicit directive: 'Use this for the legal name, DBAs, and EIN last four Mercury holds; use `list_entities` for entity keys and display names...' This names the alternative and states the split of responsibilities. No agent needs to infer when to call this tool.

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 the read-only and idempotent annotations, the description reveals important behavior: every page of GET /accounts is walked, account numbers are masked to the last four digits, and routing numbers are not returned. This gives the agent concrete expectations about data completeness and privacy handling.

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

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

The description is compact and front-loaded with the core purpose, followed by directly useful usage guidance and behavioral caveats. Every sentence contributes information an agent needs to select and call the tool correctly.

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

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

Given the output schema, annotations, and single well-documented parameter, the description fully covers the key context: what the tool returns, how to use it with downstream tools, which alternatives exist, and important masking/pagination behaviors.

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

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

Schema coverage is 100%, and the parameter description already explains that `entity` must be the exact key from list_entities, not display_name, and that it is required. The tool description adds no further parameter detail, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'List one organization's Mercury accounts with available and current balances.' It also distinguishes itself from list_credit_accounts and list_treasury, making its scope clear.

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

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

It explicitly states when to use this tool (to obtain account ids for list_transactions, list_statements, and list_cards) and names the alternatives for credit and treasury accounts, leaving no ambiguity about routing.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds that the API never returns PAN, CVC, or expiry, which is important security context. It also explains the parameter passing behavior for `account_id` and status, but doesn't mention pagination or rate limits. Since annotations cover safety, this is strong.

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 efficient, with the core purpose and return fields in the first line, followed by usage notes. It is not overly verbose, but some redundancy exists (e.g., repeating the return fields). Still, it is well-organized and front-loaded.

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

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

The tool is a list operation with moderate complexity, and annotations plus output schema cover basic expectations. The description adds key usage constraints and security notes. It doesn't mention pagination or error handling for `limit`, but given the output schema and annotations, it is sufficiently complete for most agent use cases.

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 all parameters are described in the schema. The description adds contextual value: `account_id` takes only one id but Mercury accepts several, and `limit` counts after filters. These nuances are not in the schema, so the description enhances parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists cards and enumerates the fields returned. It also distinguishes itself from `get_card` and `list_merchants`, so there is no ambiguity about its purpose.

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 instructs to use `get_card` when a card id is already known and `list_merchants` for merchants referenced by locks. It also notes that `account_id` takes only one id despite the API accepting multiple, and that unknown statuses are passed through to error. This is clear when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds the pagination behavior ('Every page is walked') and clarifies the scope is a single organization. It doesn't detail the exact return structure beyond 'id, name, visibility flags,' but given annotations, this is sufficient 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?

The description is concise, front-loaded with the primary purpose, and follows with a targeted usage note. Every sentence adds value; no fluff or repetition.

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

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

With an output schema present and readOnly annotations, the description covers what an agent needs: the tool lists categories, resolves ids/names, distinguishes from list_transactions, and explicitly states pagination is handled. Nothing critical is missing for correct invocation.

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

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

Schema coverage is 100% with a detailed description of the 'entity' parameter ('Exact `entity` key from `list_entities`, not its `display_name`. Required; there is no default.'). The description itself adds no additional parameter semantics beyond what the schema already provides, so the baseline 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?

States a specific verb ('List'), resource ('one organization's custom expense categories'), and scope ('one organization'), and differentiates from sibling list_transactions by clarifying that list_transactions carries a row's own category as categoryData. The purpose is 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?

Explicitly tells when to use this tool ('resolve category ids and names') and when not to (use list_transactions for a row's own category). Also notes 'Every page is walked,' informing the agent that pagination is handled automatically. This is clear guidance with an explicit 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 already cover read-only, idempotent, and non-destructive behavior. The description adds the unpaginated nature of the endpoint ('Unpaginated GET /credit returns every credit account'), which is valuable behavioral context beyond the 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 compact and front-loaded: it states the purpose first, then provides usage guidance in a single follow-up sentence. No filler or 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 (one required parameter), the presence of an output schema, and annotations covering safety, the description is fully sufficient. The unpaginated note removes any ambiguity about return volume, and the sibling differentiation covers selection.

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 description covers 100% of the single parameter (entity) with detailed instructions about using the exact key from list_entities and noting it is required with no default. The tool description adds no further parameter semantics, so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (List), a specific resource (credit accounts), and the key data (available and current balances). It also explicitly distinguishes itself from sibling tools list_accounts and list_cards, making the 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?

Provides explicit when-to-use guidance: 'Use this for credit accounts only' and names the alternatives for other account types. It also clarifies the unpaginated behavior, giving the agent a complete decision framework.

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 readOnly=true, idempotent=true, and destructive=false. The description adds context beyond them: 'Every page is walked' reveals automatic pagination, and the `deletedAt` note warns that deleted customers may still appear carrying that field. This aligns with openWorldHint rather than contradicting it.

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 sentences, front-loaded with the core purpose, and every clause earns its place: return-field scope, exclusion, use case plus alternative, pagination, and deleted-record behavior. No filler and no repetition of what annotations or schema already provide.

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?

Complete for a simple one-parameter list tool. The output schema covers return values, annotations cover the safety profile, and the description covers scope, usage guidance, auto-pagination, and edge-case behavior. Nothing an agent needs in order to invoke 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 description coverage is 100%; the schema already documents `entity` precisely ('Exact `entity` key from `list_entities`, not its `display_name`. Required; there is no default.'). The description adds no parameter-specific semantics beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'List accounts-receivable customers.' It also scopes the return fields ('id, name, and email') and explicitly excludes addresses ('No addresses.'). Names the sibling it is not (`list_recipients`), so an agent can differentiate without inspecting other 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 when-to-use guidance ('Use this for invoice customers') with a cross-tool linkage (ids are the `customerId` on `list_invoices` rows). Explicitly names the alternative `list_recipients` and the condition that selects it (payees the organization pays). 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, idempotentHint, and destructiveHint false. The description adds valuable behavioral detail: it states that `token_configured` only indicates whether the env var is set and non-blank, and never reveals the value, which is important for security-sensitive agents. The 'No Mercury request' note further clarifies the tool's operational behavior, going beyond the annotation safety profile.

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 compact—three sentences that front-load the primary purpose, then provide routing guidance, and finally a security-relevant note about token_configured. Every sentence earns its place with no redundancy or fluff.

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

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

For a parameterless list tool, the description is complete: it states the output fields, the primary use case, differentiates from siblings, and discloses a non-obvious behavior (token_configured never reveals the value). An output schema exists to detail the return structure, so the description does not need to repeat that. No gaps are evident.

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?

There are zero parameters, so the schema trivially covers everything. The baseline for 0-parameter tools is 4. The description does not add parameter-specific semantics (none needed), but it does clarify what the returned fields mean, which is helpful for interpreting results.

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 opens with a specific verb-resource statement ('List the configured Mercury organizations') and enumerates the output fields (entity keys, display names, token configuration). It explicitly differentiates from sibling tools by naming `server_info` and `get_org` as alternatives for other purposes, so an agent can immediately recognize what this tool does and what it does not.

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

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

The description gives a clear use case ('find the entity key the Mercury tools require') and explicitly directs the agent to `server_info` for build info and `get_org` for the legal profile, establishing when to use this tool versus alternatives. It also clarifies that no Mercury request is made, so the agent knows it is a lightweight local read.

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?

Despite strong annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description adds substantial behavioral context: the mergePatch/previousValues re-projection through each resource's own allowlist (masking account numbers, stripping bank coordinates), the 90-day feed walk with no time filter, the sorting-before-limit behavior that makes `truncated` exact, and the 400 on unknown resource_type. This is genuine value beyond annotations with 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?

The description is long but information-dense; every sentence carries behavioral, ordering, or routing value. It front-loads the core purpose and defers the fine-grained ordering/truncation details. It could arguably be tightened into clearer paragraphs, but there is no filler — it 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?

For a complex tool with 4 parameters, non-obvious ordering semantics, and an error case, the description is thorough. It covers the feed-walk behavior, masking rules, truncation exactness, the 400 on unknown resource_type, and usage routing. An output schema exists, so return-value documentation isn't needed from the description; nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema: `since` triggers a whole-feed walk filtered on `occurredAt` and sorted newest-first before `limit` applies (making `truncated` exact), and unknown `resource_type` values yield a 400. The `entity` requirement for an exact key is also echoed. This is a clear step above baseline, though some param details remain schema-led.

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 opens with a specific verb+resource: 'List the change-event feed in Mercury API desc order: what changed on which resource, with the changed fields.' This clearly states what is returned and differentiates it from sibling list tools by naming them as alternatives in the usage guidance. An agent can distinguish this from list_transactions and list_webhooks 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?

The description gives explicit when-to-use and when-not-to-use guidance: 'Use this to see what changed recently on transactions and accounts and which fields changed; use list_transactions for the transactions themselves and list_webhooks for the endpoints subscribed to these events.' It also documents the `since` semantics and the 400 error case, 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, idempotentHint, and destructiveHint. The description adds meaningful behavioral context beyond that: file names are verbatim third-party text, no download URLs, and the unpaginated nature. These details are not redundant with annotations and help the agent set expectations.

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

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

Two concise sentences with zero fluff. The purpose is front-loaded in the first sentence, and usage guidance follows immediately. Every phrase earns its place.

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

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

For a simple list tool, the description covers everything an agent needs: purpose, parameter implications, return scope (id and file name), and crucial behavioral facts (no URLs, no pagination). The schema covers parameters fully, and the output schema is said to exist. Nothing essential 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% for both parameters; the schema already explains entity (exact key, not display_name, no default) and invoice_id (from list_invoices). The description adds no new parameter-specific semantics, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('inventory'), resource ('one invoice's attachments'), and scope ('id and file name'), and differentiates from siblings by naming get_invoice and list_tax_docs as alternatives. The 'no download URLs' detail adds precision, making the purpose unmistakable.

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

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

It explicitly says 'Use this for the files attached to one invoice' and directs to `get_invoice` for the invoice itself and `list_tax_docs` for tax forms, clearly establishing when to use and when not to use. The note 'Unpaginated; every attachment is returned' adds operational guidance.

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 read-only, idempotent, open-world. The description adds crucial behavioral facts: no server-side filters (so status/date filtering walks every invoice), unknown status errors upfront, and slug omission. These go well beyond what annotations or schema reveal.

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?

Every sentence earns its place. Purpose, usage guidance, behavioral caveats, and parameter clarifications are packed into a compact, well-organized block. No redundancy, 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?

Covers purpose, filtering semantics, error behavior, provided/omitted fields, and routes to siblings. With an output schema present, the return structure is covered. Nothing needed for correct invocation is missing.

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

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

Schema coverage is 100%, but the description adds meaningful context: entity must be the exact key from list_entities (not display_name), status is case-insensitive, and limit caps the post-filter matches. This clarifies usage beyond the flat 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?

States a specific verb+resource (list invoices) and scope (accounts-receivable, optional filters), and explicitly differentiates from siblings get_invoice and list_invoice_attachments. No ambiguity about what it does or how it differs.

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

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

Explicitly tells when to use this tool (find invoice ids, filter invoices) and names the alternatives with their specific purposes (get_invoice for line items/service period, list_invoice_attachments for files). Also explains the client-side filtering consequence, so an agent can decide based on scale.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior, so the description does not need to restate safety. It adds valuable behavioral context beyond annotations: `search` is applied "by Mercury before paging" so `limit` caps the matches, and the id/name shape matches `merchantLock` on cards. This helps the agent reason about results without extra 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?

Every sentence earns its place: scope and output shape, intended use case, sibling distinction, and search/paging behavior. The content is front-loaded with the most decision-relevant fact and contains no filler or repetition of schema details.

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 annotations, full schema coverage, and an output schema, the description covers what an agent needs: what the tool returns, why to use it, when not to use it, and how search/paging behave. There are no obvious gaps that would cause an agent to misinvoke it.

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, and the description adds meaningful extra semantics about how `search` and `limit` interact: search is applied before paging, so limit caps the matched results. It also reinforces the domain semantics by connecting the returned id/name shape to card merchant locks, going beyond the schema's parameter 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 opens with a specific verb and resource: "List priority merchants (id and name)" and immediately scopes it to "card merchant locks." It actively distinguishes itself from list_transactions by stating it is "not a transaction's merchant data," so an agent can tell siblings apart 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?

It gives an explicit when-to-use instruction: "Use this to pick a merchant for a card lock" and names the alternative path: "use list_transactions for a card transaction's own merchant field." It also clarifies that the output shape matches `merchantLock` on cards, removing ambiguity about which field the returned ids map to.

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 the readOnly/openWorld/idempotent annotations, the description discloses meaningful non-obvious behavior: it "Walks every page", recipient ids are what reportable_totals matches counterpartyId against, bank coordinates and postal addresses are "never returned", and names/emails are third-party text. 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 purpose is front-loaded and every added sentence carries useful information: alternatives, pagination, id semantics, exclusions, and data quality. It is slightly dense and the parenthetical field list partly duplicates what the output schema provides, but it remains appropriately compact for the value it delivers.

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

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

Given one fully-documented required parameter, strong annotations, and an output schema, the description supplies the remaining critical context: when to use it, pagination behavior, cross-tool id semantics, privacy exclusions, and data-source caveats. Nothing an agent needs to invoke 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 description coverage is 100%, and the schema itself already documents the entity parameter thoroughly (exact key from list_entities, not display_name, required, no default). The description adds no parameter-specific details, so the baseline 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 opens with a specific verb and resource: "List one organization's payment recipients", scoped to a single organization and enumerating the fields returned. It also explicitly differentiates itself from siblings by naming list_customers and list_tax_docs, so an agent can tell them apart 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?

The description provides explicit routing: "Use this for payees the organization pays; use `list_customers` for invoice customers and `list_tax_docs` for which recipients have a W-9 on file." This gives both positive and negative usage guidance with named alternatives, 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 read-only, idempotent, open-world, and non-destructive traits. The description adds substantial context beyond annotations: metadata-only responses, masking of account number/EIN to last four, excluded fields, transactionCount summarizing the transaction list, and specific date-bound validation rules. 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?

Front-loaded with the core purpose, then uses compact sentences to convey alternatives, exclusions, masking, and validation rules. No filler; every sentence earns its place by contributing to correct invocation.

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?

An output schema exists, so return fields need not be restated. The description covers all critical behavioral expectations, edge cases, exclusions, and validation rules an agent needs for correct invocation, making it complete for a tool of this 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?

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining start/end constraints (at most 3 months apart, real calendar dates, end not before start, future end treated as today) and clarifying entity/account_id provenance from list_entities/list_accounts, raising it above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb, resource, and scope: 'List one account's monthly statements (metadata only) in Mercury API desc order.' It explicitly names sibling tools it is not (list_treasury_statements, get_statement_pdf), making its purpose unambiguous and distinct from related endpoints.

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 routing: use this for checking/savings statements, list_treasury_statements for treasury accounts, and get_statement_pdf for the document itself. It also covers the credit-account edge case, leaving no doubt about when this tool should be selected over 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond those hints: it walks every page of two endpoints, `formType` can be unknown or null, `fileName` is untrusted third-party text, and download URLs are not returned. This is exactly the kind of non-obvious behavior an agent needs to know before calling the tool.

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 compact and front-loaded with the core purpose, then adds usage routing and behavioral caveats. Every sentence earns its place, though the final sentence about download URLs could arguably be folded into the behavioral notes. Overall it is well-structured and not bloated.

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 moderate complexity, the rich annotations, and the presence of an output schema, the description covers everything an agent needs: purpose, alternatives, pagination, edge cases in the data, security caveats, and parameter semantics. There is no obvious gap that would cause an agent to misinvoke 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?

Schema description coverage is 100%, so the schema already documents the `entity` parameter. The description adds meaning by explaining that `entity` is the exact key from `list_entities`, not the display name, and that it is required with no default. This goes beyond the schema's own description and helps the agent supply the correct value.

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 opens with a specific verb ('Inventory') and a precise resource ('recipient tax-form attachments'), enumerates the relevant form types, and immediately distinguishes itself from sibling tools by naming `list_recipients` and `list_treasury_statements`. This makes the tool's purpose unmistakable and differentiates it from the large sibling set.

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 this tool ('for which recipients have a tax-form attachment on file') and names the alternatives (`list_recipients` for recipient details, `list_treasury_statements` for a treasury account's own tax forms). It also clarifies the pagination behavior and the meaning of `recipients_without_docs`, leaving no ambiguity about when this tool is the right choice.

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, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds important behavioral context: start/end go unvalidated and filter on createdAt, while dashboard may show postedAt, so results can differ. It also warns that memos/counterparty names/bank descriptions are third-party text to treat as data, and explains the truncated flag for pagination. No contradictions 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 a single dense paragraph but front-loaded with the core purpose and then systematically covers alternatives, caveats, and security note. Every sentence adds value, though it's a bit long. It could be broken into bullets, but it's still concise enough. 4.

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

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

For a read-only list tool with an output schema and high schema coverage, the description covers the essential caveats: pagination via truncated, filtering discrepancy, and third-party text warning. It also routes to siblings. It doesn't mention rate limits or auth, but annotations cover safety. Given the complexity, it's quite complete. 4.

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 baseline is 3. The description adds value by clarifying that start/end filter on createdAt and are passed unvalidated, which is not explicit in the schema. It also hints that cardId in rows corresponds to get_card's id, but that's output-related. Overall it enriches parameter understanding slightly, so a 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool lists one organization's transactions in `desc` order with optional filtering. It also differentiates from siblings by naming specific alternatives for other use cases, so an agent can distinguish it from reportable_totals, list_treasury_transactions, and list_events.

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 directs when to use this tool versus alternatives: 'Use this for transaction rows; use reportable_totals for per-recipient 1099 totals, list_treasury_transactions for a treasury ledger, and list_events for recent changes.' Also notes the createdAt vs postedAt discrepancy to set expectations against the UI.

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 annotations already declare readOnly, idempotent, and non-destructive behavior, so the description's burden is lower. It adds useful behavioral context beyond the annotations: it specifies that pagination is transparently handled ('Every page is walked') and describes the returned data (balances, status, monthly net returns). These details clarify observable behavior without contradicting any annotation.

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

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

The description is compact and front-loaded. The first sentence states the primary action and output, the second sentence provides routing to siblings, and the third conveys pagination behavior. Each sentence contributes distinct value with no redundancy or filler, making it easy to scan.

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 presence of an output schema, the description does not need to elaborate on return formats. It covers the scope (one organization), the differentiation from `list_accounts`, the consumer tools that rely on its ids, and pagination behavior. An agent receives all necessary information to invoke this tool correctly without needing to inspect additional resources.

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 for the sole parameter `entity` is fully documented (100% coverage) with an explanation that it is the exact `entity` key from `list_entities`, not the display name, and that it is required with no default. The description does not add new parameter-specific information beyond what the schema provides, so it satisfies the baseline for full schema coverage but does not go further.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'List one organization's treasury accounts' with the output fields ('balances, status, and monthly net returns'). It also distinguishes itself from closely related siblings by explicitly naming `list_accounts` as the alternative for checking/savings, and by noting that `list_treasury_transactions` and `list_treasury_statements` consume the ids produced here. This makes the purpose clear and disambiguates it from the sibling set.

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

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

The description provides explicit when-to-use guidance: 'Use this for treasury account ids' and directs the agent to `list_accounts` for checking and savings accounts. It also mentions a notable aspect of usage—'Every page is walked'—informing the agent that pagination is automatically handled. This leaves no ambiguity about the intended invocation context.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavior beyond annotations: pagination is walked automatically, documents are only exposed via presigned downloadUrl (not returned/fetched), and the note about `get_statement_pdf` possibly accepting treasury ids. This is useful context not encoded in annotations.

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

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

The description is well-structured and front-loaded with the primary purpose in the first line, then efficiently branches into usage distinctions and behavioral notes. It is slightly verbose (the `get_statement_pdf` aside is arguably tangential) but each sentence earns its place by conveying distinct, non-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 moderate complexity (3 parameters, output schema exists, annotations cover safety), the description is nearly complete. It covers usage distinctions, pagination behavior, document_type validation, and the downloadUrl limitation. The only minor gap is that it does not describe the exact return structure, but the presence of an output schema offloads that responsibility. Overall, it gives an agent enough to call it correctly.

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

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

Schema description coverage is 100% for all three parameters, so the schema already documents `entity`, `treasury_id`, and `document_type` with origins and constraints. The description adds minimal extra parameter semantics—it restates the treasury_id origin and document_type validation, but those are already in the schema. With full schema coverage, a baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('List one treasury account's statements and tax documents') and explicitly differentiates from sibling tools by naming `list_statements` and `list_tax_docs` with their distinct scopes. This gives an agent a clear, unambiguous purpose.

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

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

The description provides explicit when-to-use guidance by contrasting with alternatives: 'Use this for treasury statement and tax-form metadata; use `list_statements` for checking and savings statements and `list_tax_docs` for W-9 forms.' It also clarifies a key behavior (`document_type` not validated locally) and page walking, so an agent knows exactly when to invoke this tool.

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 idempotentHint, but the description adds significant behavioral detail: the API lacks date filters, so with start/end it walks up to 200 pages of 1000, filters on canonicalDay, sorts newest-first, and makes 'truncated' exact. Without a window, it returns the API's desc order as-is. This goes well beyond the annotations and discloses edge cases and pagination behavior.

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 front-loaded with the core purpose, then uses a second paragraph for the important behavioral caveats. Every sentence contributes to correct usage—no fluff. The structure separates the simple case from the windowed case clearly, and the sibling reference is placed at the end for context.

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 tool with 5 parameters and 2 required, the description covers the unusual API limitations, the pagination strategy, sorting, and the truncation semantics. An output schema exists, so return format is covered. The tool's read-only and idempotent nature is already in annotations. Nothing an agent needs to invoke 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 the baseline is 3. The description adds context for 'start' and 'end' by explaining how they trigger a full ledger walk and the resulting sort and limit behavior. It also clarifies that 'entity' must be the exact key from list_entities. This adds value beyond the schema's own descriptions, justifying a 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb-resource pair: 'List one treasury account's ledger transactions'. It also explicitly contrasts with sibling 'list_transactions' for bank-account transactions, making the tool's scope unambiguous. The distinction is clear without needing to inspect 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?

It explicitly states when to use this tool ('Use this for one treasury account's ledger') and when to use an alternative ('use list_transactions for the organization's bank-account transactions'). It also explains the behavior when date filters are provided versus not, which guides correct invocation.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds behavioral context beyond the annotations by disclosing that pagination is automatic ('Every page is walked') and that results are keyed by userId. This is useful, non-obvious behavior that an agent would otherwise have to infer from the output schema or by trial.

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 compact and front-loaded: the first sentence states the action, resource, and return fields. The second sentence provides routing guidance and pagination behavior. Every sentence earns its place; there is no filler or repetition of schema content.

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

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

For a simple read-only list tool with one parameter, a full output schema, and comprehensive annotations, the description is nearly complete. It covers what is returned, how to select the right sibling, and pagination behavior. The only minor gap is that it doesn't explicitly state the output shape (e.g., that results are in an array), but the output schema already covers that, so the description need not repeat it.

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 the schema already fully documents the single parameter (entity). The description adds a small but meaningful clarification: the entity must be the exact `entity` key from `list_entities`, not its `display_name`, and that it is required with no default. This goes slightly beyond the schema's own description, but since the schema already covers the parameter, a 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 states a specific verb ('List'), a specific resource ('one organization's Mercury users (team members)'), and the exact fields returned (id, first and last name, email, role). It also distinguishes itself from siblings by naming list_recipients and list_customers as alternatives for different entity types, so an agent can tell them apart 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?

The description explicitly says when to use this tool ('for users and their roles') and when not to ('use list_recipients for payees and list_customers for invoice customers'). It also notes that every page is walked and keyed by userId, which is a clear usage detail. This is explicit routing guidance with no ambiguity.

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 read-only, idempotent, open-world, and non-destructive behavior. The description adds critical non-obvious context: it never returns the signing secret or receiver URL because the URL is a capability, explains the url_fingerprint derivation, and states that 'Every page is walked' (pagination behavior). This goes well beyond the annotations with 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?

The core purpose and returned fields are front-loaded in the first sentence. Each subsequent sentence adds distinct value: security constraints, fingerprint semantics, tool routing, and pagination. There is no filler.

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

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

For a one-parameter list tool with a rich output schema and strong annotations, the description covers purpose, security-sensitive omissions, alternative-tool routing, and pagination. Nothing an agent needs to invoke 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?

The input schema fully documents the single entity parameter with 100% coverage, so the schema carries the burden. The description does not add parameter-specific detail, so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific action ('Read-only view of webhook endpoints') and enumerates the returned fields: id, url fingerprint, status/enabled, event types, filter paths. It also explicitly differentiates itself from list_events, so an agent can tell them apart.

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 routing guidance: 'Use this for the webhook configuration ... use list_events for the events themselves.' This makes the choice between siblings unambiguous. The schema also adds the requirement to pass the exact entity key from list_entities.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description goes far beyond annotations: it states 'it never files anything', explicitly qualifies which transactions count ('status sent', outgoing negative amounts), explains time attribution ('postedAt in UTC'), discloses the padded query window and that out-of-year rows are counted in excluded_summary.outside_year, and that a failed walk is an error, never a partial total. It also details classification logic and the treatment of counterparty names as data, not instructions. This is a rich, transparent behavioral description.

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 long but every section earns its place: the opening states purpose, then usage, then detailed classification tables, grouping rules, and a security note. It is well-organized with clear headings and bullets. There is no fluff or repetition; the length is justified by the tool's complexity. The most important purpose and usage guidance are front-loaded.

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

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

Given the tool's complexity and that an output schema exists, the description covers all necessary context: what is included/needs review/excluded/unclassified, how recipients are grouped (counterpartyId confidence), nuance about real-time payments and USD amounts, and the security caveat about third-party text. It even mentions that the classification table lives in docs and that live docs define no semantics for kinds. Complete for an agent to decide and invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. However, the description adds substantial meaning beyond the schema: it explains entity is the 'Exact entity key from list_entities, not its display_name', specifies year attribution by 'postedAt (UTC)', and gives detailed threshold semantics (default depends on tax year: 600 through 2025, 2000 from 2026, inflation-indexed from 2027), rounding ('rounded to cents, half up'), and the fact that out-of-range values are rejected before any request. These are meaningful additions, not just restatements.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description opens with a specific, informative statement: 'Per-recipient totals of payments the organization MADE in a year, classified for a 1099 cross-check.' It names the resource (payments), the verb (totals), and the context (1099). It also distinguishes itself from sibling tools explicitly: 'Use this for a per-recipient 1099 total for one tax year; use list_transactions for individual rows and list_tax_docs for which payees have a W-9 on file.' No ambiguity remains.

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

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

The description clearly states when to use this tool vs alternatives: 'Use this for a per-recipient 1099 total for one tax year; use list_transactions for individual rows and list_tax_docs for which payees have a W-9 on file.' It also provides strong exclusionary context: 'This is a pre-filing cross-check only; it never files anything, and Mercury has no filing endpoint.' It also warns about the wrong filter type ('not the createdAt filters used by list_transactions'). This is exemplary when-to/when-not guidance.

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, idempotent, and non-destructive. The description adds context that it returns specific build details and excludes secrets, which is useful and goes beyond annotations. It doesn't contradict annotations, and the added detail about no Mercury request clarifies internal behavior.

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 succinct, front-loads the key information about the build, and uses only two sentences. Every phrase earns its place, including the explicit pointer to list_entities and the note about no Mercury request.

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

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

Given the tool's complexity (zero params) and the presence of an output schema, the description is complete. It covers purpose, key outputs, exclusions (secrets), and how to get related data (entity keys). Nothing critical 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?

The tool has zero parameters, and the schema coverage is 100%, so there is nothing to document. The description still provides value by explaining what the output will contain, which is more than a bare schema would offer. The baseline for 0 params is 4, and this is met.

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 reports the running build with specifics: package version, API base, entity count, and documents_enabled flag. It distinguishes itself from sibling tools by explicitly mentioning list_entities for entity keys and emphasizing no Mercury request.

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

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

It gives explicit guidance on when to use: to check build and documents_enabled, and directs to list_entities for entity keys. It also states what it does NOT do, such as making a Mercury request, which helps avoid misuse.

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