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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the description's marginal job is the side-effect profile — and it delivers the key fact that no email is dispatched. It still omits what happens on failure (invalid ID, non-draft state) and what the mutated estimate looks like afterward.

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 short sentences, front-loaded with the action and immediately followed by the most likely point of confusion (that it does not send an email). 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 mutation with annotations covering safety and idempotency and no output schema, the description supplies everything an agent needs to pick and call it correctly: the action, the state prerequisite, and the absence of an email side effect.

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 single estimateId parameter is 100% documented in the schema, so the description owes nothing extra there and provides nothing extra. Baseline 3 applies for a high-coverage schema with one 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?

States a specific verb and resource ('Approve a draft estimate') plus the resulting state transition ('so it can be sent'). The clause 'Does not email it' separates it from the sibling send tools (wave_send_estimate, wave_send_estimate_acceptance_email) without naming them.

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?

Implicitly tells the agent to use this when a draft needs to become sendable, and rules out emailing as its effect. It does not name the alternative tool to call for sending, nor state the precondition explicitly as a requirement (what happens if the estimate isn't a draft).

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 annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses the resulting state (SAVED) and the accounting consequence of posting to the books, which is exactly the context a mutation tool needs. It does not cover failure behavior for non-draft invoices or whether the approval can be reversed.

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

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

Two sentences, no filler, with the effective state change front-loaded and the negative scope (no email) placed last. Every clause 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 single-parameter mutation with annotations and no output schema, this covers what the tool does and what state it leaves behind. The only real gap is preconditions and error behavior for invoices that are not in draft.

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) exists and schema description coverage is 100%, so the schema already carries the semantics. The description adds nothing about the identifier's origin or constraints, 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 ("Approve a draft invoice") plus the concrete effect ("posts it to the books (status SAVED)"). The closing clause "Does not email it" separates it from wave_send_invoice and wave_mark_invoice_sent without needing to open 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?

The word "draft" implicitly scopes when this applies, and "Does not email it" steers the agent away from conflating this with sending. It stops short of naming siblings explicitly (e.g. use wave_send_invoice to deliver it) or stating what happens on a non-draft invoice.

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 destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds context annotations cannot carry: the two server-side refusal conditions and the fact that the action is irreversible through the API ('No un-archive'). That is precisely the risk information an agent needs before calling a destructive 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?

Three short sentences, no filler: the operation's effect first, then the refusal conditions, then the irreversibility warning. Each sentence carries information an agent would otherwise have to discover by failing the call.

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 destructive mutation with no output schema, effect, preconditions and irreversibility are all covered. A minor gap remains around what happens to linked transactions/reports after archiving, but nothing required to invoke the 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?

There is a single required parameter with 100% schema description coverage, so the schema already documents 'Account ID'. The description adds no further meaning about the id (format, where to obtain it), which is the baseline 3 when the schema does the work.

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 and then glosses the operation's semantics: 'hide it while keeping its history.' That gloss is what distinguishes archive from delete, and the resource word distinguishes it from the sibling wave_archive_product and wave_archive_sales_tax.

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-not conditions — Wave refuses for system accounts and accounts with a balance — which is exactly the guidance an agent needs before attempting the call. It stops short of naming a sibling alternative (e.g. wave_update_account for making an account inactive-by-other-means), so it is not a full 5.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description earns credit beyond that by disclosing two non-obvious behaviors: past invoices retain the product, and the archive is irreversible through the API. It doesn't say what happens to existing recurring or draft invoices, which is the remaining gap.

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 short sentences, zero filler, and the primary effect is front-loaded before the edge cases. Each sentence contributes a distinct fact: effect, invoice history, irreversibility.

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 destructive mutation with no output schema and safety already covered by annotations, the description covers effect, historical scope, and reversibility. Only secondary consequences (recurring invoices, estimates referencing the product) are left implicit.

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 is one required parameter at 100% schema coverage, and the schema already labels it "Product ID". The description adds no meaning about the id (for example, whether it accepts an internal ID versus a display name), 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?

"Archive a product/service" gives a specific verb and resource, and the qualifier "so it can no longer be added to new invoices" states the observable effect. The agent can distinguish this from wave_update_product or wave_list_products by the archive semantics, though no sibling is named explicitly.

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

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

The description implies the use case (retiring a product from future invoices) but never states when to prefer this over wave_update_product or how it relates to other product tools. The one routing fact given -- un-archiving is web-app only -- is about recovery, not 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 declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description still earns credit for spelling out the semantic consequence — the tax can no longer be applied — and for explicitly stating there is no API path to undo it, which goes beyond the hints. It doesn't say what happens to historical invoices/transactions already using the tax.

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 short sentences, the effect front-loaded and the irreversibility constraint immediately after. No padding, nothing redundant with the title.

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, no-output-schema mutation, the description covers the effect and irreversibility, which are the essentials. The notable remaining gap is whether already-issued invoices keep referencing the tax, which matters for a destructive operation.

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 the single 'id' parameter, so the schema fully documents the input. The description adds no meaning about the ID format or what a bad/missing ID returns, 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 ('Archive') and resource ('sales tax') and adds the consequence ('can no longer be applied'), so the agent knows the operation's effect. It doesn't contrast with sibling archive tools (archive_product, archive_account), but the name plus description makes the target resource 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 phrase 'No un-archive through the API' signals a when-to-use caution by flagging irreversibility, which is real guidance. However, it never names an alternative (e.g., update_sales_tax to modify rather than retire a tax) or states prerequisites such as whether the tax must be unused first.

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=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the safety profile is covered. The description adds one genuinely new fact beyond annotations – the copy lands as a draft – but says nothing about what is carried over (line items, customer, dates), whether a new ID is issued, or that the source is untouched, and idempotency/non-idempotency implications of repeated calls are unaddressed.

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?

A single front-loaded sentence with zero filler, which is appropriate for a one-parameter clone. It is efficient but so terse that a brief clause on what is copied or what is returned would have been nearly free to include.

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 one-param clone with annotations carrying the safety profile, the definition is minimally sufficient to call correctly. However, with no output schema the description is the only place an agent could learn what comes back (new estimate ID? draft object?) or which fields are carried over, and it provides neither.

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% with a single parameter documented as 'Estimate ID', so the schema carries parameter meaning. The description only implies that this ID is the source estimate to be copied; it adds no format, prefix, or sourcing 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?

Names a specific verb (copy/clone) and resource (estimate) and states the outcome state ('a new draft'), which separates it from wave_create_estimate and wave_convert_estimate_to_invoice. It does not explicitly name the closest sibling (wave_clone_invoice) or contrast the two, but 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?

Usage is only implied by the word 'copy' – an agent can infer 'use this when you want a duplicate rather than a fresh estimate', but nothing states when NOT to use it (e.g. converting vs cloning) or that the source estimate is left unchanged. No alternatives are named despite several adjacent estimate 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 establish that this is non-read-only, non-destructive, and non-idempotent. The description usefully adds that the result is a 'new draft,' implying the source invoice remains unchanged, but it does not say what fields are copied, whether the draft is editable or sendable, or that repeated calls may create multiple drafts.

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 short sentence that front-loads the action and states the outcome. There is no filler or redundant wording.

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 clone operation, the essential call mechanics are covered by the schema and annotations, and 'new draft' communicates the output state. However, an agent choosing among many invoice tools receives no information about what is copied or how this differs from wave_create_invoice, leaving a meaningful selection gap.

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

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

There is only one parameter, and its schema description covers 100% of the field, including type and required status. The description does not add selection guidance or formatting detail for invoiceId, so it meets the baseline without adding meaning beyond the schema.

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

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

The description uses a specific verb ('Copy') and resource ('invoice') and states the resulting state ('new draft'), so the core action is clear. It does not differentiate from nearby tools such as wave_create_invoice or wave_clone_estimate, so tool selection still relies partly on the name.

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 phrase 'into a new draft' implies this is for duplicating an existing invoice rather than creating one from scratch. However, there is no explicit when-to-use, when-not-to-use, prerequisite, or named alternative such as wave_create_invoice or wave_clone_estimate.

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 non-read-only, non-idempotent, non-destructive behavior, and the description adds genuinely useful context beyond them: deposits paid carry over to the new invoice, and the new invoiceId is returned. It stops short of saying whether the source estimate is modified or left intact, and does not warn that repeated calls will create duplicate invoices.

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 short clauses, both load-bearing, with the transformation rule and the return value front-loaded. Nothing is wasted.

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 conversion tool with annotations covering the safety profile and no output schema, the description supplies the essential side effect (deposit carryover) and the return shape. Only the fate of the source estimate and duplicate-call risk are left unstated.

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 is a single parameter with 100% schema description coverage, so the schema already carries the burden. The description adds no format, source, or constraint detail about estimateId, making the baseline 3 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 and resource ('Create an invoice from an estimate') plus the key transformation rule (deposits carry over). This clearly distinguishes it from generic siblings like wave_create_invoice and wave_clone_invoice without needing to name them.

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 conversion framing implies when to use it — when an estimate should become an invoice — but there is no explicit when-not guidance versus wave_create_invoice or wave_clone_estimate, and no prerequisites such as estimate status requirements.

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 is consistent with the annotations: 'Add' aligns with readOnlyHint=false and destructiveHint=false. It adds the useful behavioral detail that subtype determines account type, but it does not elaborate on permissions, validation, duplicate handling, or other mutation consequences beyond what the annotations already say.

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 short sentences with no filler, front-loaded with the action and followed by the key subtype dependency. Nothing is wasted.

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 six-parameter create tool with no output schema, the definition covers the core action and the most important subtype relationship. It remains thin on mutation behavior, return expectations, duplicate constraints, and business-context requirements, leaving meaningful gaps for an agent invoking 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 only 50%, so the description should compensate more than it does. It adds meaningful semantics for subtype by explaining that it decides the account type and pointing to wave_get_reference, but it says nothing about name, description, duplicate naming, or the other optional parameters 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?

The description states a specific verb and resource: 'Add an account to the chart of accounts.' That distinguishes creation from sibling tools such as wave_update_account and wave_archive_account, though it does not explicitly name those alternatives.

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?

Usage is implied by 'Add an account', and the pointer to wave_get_reference for subtype selection gives practical setup guidance. However, it does not say when to create versus update, archive, or list accounts, nor does it state prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. Beyond that the description adds nothing: it does not say whether duplicates are rejected, whether email/currency are validated, or what the call returns. For a write tool with 15 parameters this is thin.

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 short sentences, front-loaded with the action. Nothing is padded, but the second sentence earns little since it duplicates the required field already encoded in the schema.

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 15 parameters, nested address and shippingDetails objects, no output schema, and only 40% schema description coverage, the description leaves most of the tool's contract undocumented. An agent cannot tell what identity fields to prefer (name vs firstName/lastName), how businessId defaults, or what comes back after creation.

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

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

Schema description coverage is only 40%, so the schema does not document fax, phone, mobile, website, firstName, lastName, internalNotes, or shippingDetails on its own. The description compensates with the single phrase "only name is required," which merely restates the schema's required array and leaves the other 14 parameters unexplained.

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 ("Create a customer"), which is unambiguous against siblings like wave_update_customer, wave_delete_customer, or wave_create_invoice. It stops short of any sibling routing (e.g. when to reuse wave_update_customer instead), so it stays at 4 rather than 5.

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?

"Only name is required" is a parameter fact, not usage guidance. There is no statement of when to use this versus wave_get_customer, wave_list_customers, wave_update_customer, or the generic wave_graphql_query, and no mention of duplicate-detection or preconditions.

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=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the record is created in draft state and no email is dispatched, which an agent could not infer from annotations alone.

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

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

Four short sentences, front-loaded with the core action and result state. No filler, though the deposit sentence is vague about which parameters it maps to.

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 31-parameter mutation tool with low schema description coverage and no output schema, the description is far too thin. An agent gets no guidance on currency/exchangeRate interplay, discount scale verification, businessId defaulting, or what the created draft returns.

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 26% across 31 parameters, so the description carries a heavy compensation burden and does not meet it. It restates the two required line fields (already in the schema's required array) and mentions an optional deposit, but says nothing about currency, exchangeRate, discounts, businessId defaulting, or the many hide*/title* layout flags.

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 ('Create a draft estimate (quote)') and clarifies the creation result is a draft. 'Nothing is emailed' implicitly separates it from wave_send_estimate, though no sibling is named explicitly.

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?

Usage is only implied: 'draft' and 'Nothing is emailed' hint that this is the pre-send creation step versus wave_send_estimate or wave_create_invoice. No explicit when-to-use, prerequisites, or named alternative is given.

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 annotations, the description discloses important behavior: default DRAFT status, defaulting of invoice number/dates/title/notes from business settings, per-product tax defaults, and that no email is sent. It does not cover return shape or permission requirements, but it adds substantial context for a mutation 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 four short sentences with no wasted wording. It front-loads the core action and follows with the most decision-relevant defaults and side effects.

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 28-parameter creation tool, the description covers the key behavioral facts an agent needs: draft versus saved state, tax defaults, defaulted invoice fields, and no email. The richer schema fills in many parameter details, though the description could say more about the created object's return.

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 low at 21%, so the description must compensate. It adds meaning for status, tax handling, and several defaulted fields, but it leaves many of the 28 parameters, such as discounts, currency, exchange rate, and the hide/disable flags, unexplained.

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: create an invoice for a customer. It also distinguishes the operation from sending by explicitly saying nothing is emailed, so an agent can tell it apart from wave_send_invoice and wave_mark_invoice_sent.

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

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

It gives clear context for use: the invoice is created as DRAFT unless status=SAVED, and nothing is emailed. It does not explicitly name alternatives such as wave_send_invoice or wave_approve_invoice, but the intended usage is clear.

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=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the agent knows this is a non-destructive local write. The description adds that providing account IDs changes downstream behavior (sellable on invoice lines), which is genuine context. But it is silent on the practical consequences of idempotentHint=false — that repeated calls may create duplicates — and on what is returned or what errors arise from mismatched account subtypes.

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

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

Two tight sentences with zero filler, and the core action is front-loaded before the optional configuration detail. Every clause earns its place by telling the agent something about how the account IDs affect the created item.

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 7-parameter creation tool with no output schema, the description covers the what and the sellable/buyable configuration but omits the return payload (presumably a product ID) and any note about duplicate creation given idempotentHint=false. It is adequate to make the call, but a meaningful mutation tool warrants slightly more.

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 71%, so the schema already documents unitPrice, businessId, incomeAccountId, expenseAccountId and defaultSalesTaxIds with meaningful detail. The description largely restates the income/expense account meaning already present in the property descriptions and adds no format or constraint detail beyond that. A baseline 3 is appropriate given the schema does most of the work, with three undocumented fields (name, description, defaultSalesTaxIds semantics) left thin.

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 ('Create a product or service'), which is immediately distinguishable from siblings like wave_update_product, wave_archive_product and wave_list_products. It does not name those alternatives explicitly, but the create verb alone 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?

It explains the configuration choice well: supply incomeAccountId to make the item sellable, expenseAccountId to make it buyable, or both. However, it never says when to prefer this over alternatives (e.g., creating an account first via wave_create_account, or checking for an existing product with wave_list_products) nor what prerequisites must be resolved 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 already indicate this is a non-readonly, non-idempotent mutation. The description adds a useful behavioral constraint: abbreviation must be unique within the business. However, it does not explain duplicate-handling behavior, permission requirements, or what happens on success beyond creating the tax.

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 appropriately brief and front-loaded, stating the core action first and the key constraint second. The max-length mention slightly duplicates the schema, but the uniqueness detail is a valuable addition and no sentence is wasted.

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 9-parameter mutation tool with no output schema, the description is minimally adequate. It covers the primary action and one important validation rule, but lacks detail on error behavior, required permissions, and expected response or created-tax lifecycle.

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 56%, with useful descriptions for rate, businessId, taxNumber, isCompound, and isRecoverable. The description only adds the abbreviation uniqueness rule and repeats the max length constraint. It does not compensate for undocumented parameters such as name, description, and showTaxNumberOnInvoices.

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: 'Create a sales tax.' This clearly distinguishes it from sibling tools like wave_list_sales_taxes, wave_get_sales_tax, wave_update_sales_tax, and wave_archive_sales_tax. It does not explicitly name those siblings, but the CRUD distinction is unambiguous from the name and description.

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?

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. The only usage-related detail is the abbreviation uniqueness constraint, which is a validation rule rather than selection 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?

Goes well beyond the annotations by disclosing that Wave does not document de-duplication by externalId, advising a check of the web app after a timeout rather than blind retry, and telling the agent to retain the returned id for later reads. These are exactly the operational risks (duplicate writes, lost ids) an agent needs before calling a non-idempotent create.

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 carries weight: the two patterns, the balancing rule, the id-retention note, the dryRun escape hatch, and the dedupe caution. It is front-loaded with the modeling rules and telegraphic without becoming ambiguous.

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 an 8-parameter nested create with no output schema, the description covers the hard parts: double-entry construction, balancing, validation, and duplicate risk. Minor gaps remain around tax line handling and the customerId/notes fields, which the schema alone must carry.

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 75%, and the description still adds real meaning: it explains the anchor/line relationship, maps direction DEPOSIT/WITHDRAWAL to money in/out through concrete examples, and shows which account types go in the anchor vs. the lines. It leaves taxes, customerId, and the businessId default to 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 gives a specific verb and resource: 'Record a bank/credit-card transaction and categorize it,' and anchors it to the familiar Wave Transactions page. It differentiates from the read path (wave_get_transaction / wave_list_transactions) but never mentions the bulk sibling wave_create_transactions, so an agent cannot fully disambiguate single vs. batch creation from this text 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?

Provides two concrete worked patterns (expense paid by card vs. sale deposited to bank), the rule that line items must total the anchor, and an explicit validate-without-writing path via dryRun=true. It does not state when to prefer this over wave_create_transactions or wave_import_ledger, which is the main remaining routing gap.

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 the safety profile (not read-only, not destructive, not idempotent, closed-world), while the description adds real behavior: all-or-nothing validation ('nothing is sent if any fails'), the checks performed, and path-based error reporting (transactions.N...). It omits the dryRun flag's effect and does not address idempotency/retry behavior, which matters for a non-idempotent batch write.

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

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

Three sentences, front-loaded with the batch limit and the sibling reference; nothing is filler. Parenthetical asides ('same shape as ...', 'transactions.N...') add value rather than noise, though the middle clause is slightly compressed.

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 mutation tool with a large nested schema and no output schema, the description covers atomicity, validation and error shape well. The notable residual gaps are what a successful response contains (created IDs, externalIds?) and how dryRun changes the outcome, both of which an agent would want before calling.

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 low (33%), so the description needs to carry weight; it contributes the 50-item cap and a shape pointer to wave_create_transaction, but leaves the top-level dryRun flag completely unexplained in both schema and description. The nested transaction fields are well documented in the schema, so the gap is mostly at the top level.

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 ('Create ... money transactions'), quantifies scope ('up to 50 ... in one request') and anchors to the sibling ('same shape as wave_create_transaction'), so the agent can immediately distinguish it from the single-transaction tool.

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 bulk-vs-single distinction is clear from the 50-item cap and the 'same shape as wave_create_transaction' pointer, which implies this tool is for batches. It stops short of an explicit routing rule ('use wave_create_transaction for a single entry') or any statement of when not to use bulk.

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 destructiveHint=true and idempotentHint=true, so the safety bar is partly covered. The description goes well beyond them by disclosing the exact post-condition: removal from lists, continued readability by ID via wave_get_customer with deleted: true, and the absence of any undelete path.

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

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

Two tight sentences, front-loaded with the action and then the critical consequence. Every clause earns its place, including the pointer to wave_get_customer and the no-undelete warning.

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 delete with full annotation coverage and no output schema, the description supplies exactly the missing pieces: what actually happens to the record and that the action is irreversible through the API. Nothing an agent needs before invoking it is absent.

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 is a single required parameter (id) and schema description coverage is 100%, so the schema already documents it as 'Customer ID'. The description adds nothing about the identifier's format or source, which is acceptable at this 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?

Names a specific verb (delete) and resource (customer) and immediately clarifies the semantics: a soft delete that removes it from lists while keeping the record retrievable by ID. An agent can distinguish this from wave_update_customer or wave_get_customer without reading 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?

Usage is implied by the destructive nature and the note that there is no undelete, which is a useful warning. However, the description never explicitly says when to choose deletion versus updating the record, nor does it route the agent to any alternative (e.g., if it only wants to hide a customer from lists).

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The word 'Permanently' reinforces irreversibility but adds little beyond the annotation; nothing is said about side effects on linked invoices, payments, or permissions. That is adequate but thin for a destructive operation.

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?

One short, front-loaded sentence with no redundant wording; the destructive nature is stated immediately. Nothing in it 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?

For a simple one-parameter tool with a full annotation set and no output schema, the description is minimally sufficient to call it. However, a destructive estimate operation would benefit from noting constraints such as acceptance/conversion state or cascading effects, which are absent.

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 is a single parameter with 100% schema description coverage, so the schema already carries the semantic load. The description adds no format, sourcing, or validation hints beyond what the schema states.

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 ('Permanently delete an estimate'), which lets an agent distinguish it from sibling deletion tools such as wave_delete_estimate_payment and wave_delete_invoice. It does not explicitly name those siblings or state scope limits, so it falls short of a 5.

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?

There is no when-to-use guidance, no prerequisites (e.g., whether an accepted or converted estimate can be deleted), and no pointer to alternatives like wave_update_estimate or archive-style operations. The agent must infer everything about timing from the tool name.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is fully covered by structured data. The description adds almost nothing beyond that: it does not say whether the deposit's associated transaction is also removed, whether the estimate balance is recalculated, or whether the deletion is reversible.

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?

A single short sentence that is front-loaded with the action and has no filler or redundancy. It is efficient but borders on under-specification rather than tight communication.

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 destructive mutation with no output schema, the description should explain the consequences of deletion and the relationship to the parent estimate and underlying transaction. It says only that the payment is deleted, leaving the agent to guess at side effects before performing an irreversible operation.

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 a single parameter at 100% schema description coverage ('Estimate payment ID'), the schema already carries the meaning, so the baseline of 3 applies. The description contributes no additional detail about ID format, source, or whether an estimate-scoped ID is accepted.

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 uses a specific verb and resource ('Delete a recorded estimate deposit payment'), which is far clearer than a tautology. However, it does not distinguish this tool from close siblings such as wave_delete_estimate (removes the whole estimate) or wave_update_estimate_deposit / wave_record_estimate_deposit, so an agent must infer the boundary from names 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?

There is no when-to-use or when-not-to-use guidance, no prerequisite that the payment must already be retrieved via wave_get_estimate_payment, and no pointer to the alternative of updating rather than deleting. The only implied guidance is the word 'recorded', which hints at a precondition but never states it.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is largely covered. The word 'Permanently' usefully reinforces irreversibility, but the description says nothing about effects on linked records such as payments or whether deletion fails when an invoice has payments attached.

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?

One short sentence, front-loaded with the verb and resource, with no filler or repetition. Its brevity is close to under-specification but nothing written is wasted.

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 destructive, single-parameter mutation with no output schema, the safety hints are supplied by annotations, so the description need not explain return values. However, an irreversible delete should say what happens to dependent data and what errors are possible, and that is absent.

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 is a single parameter with 100% schema description coverage, so the schema itself documents invoiceId. The description adds no semantics about format, source of the ID, or whether IDs come from wave_list_invoices or wave_get_invoice, which is the baseline expectation when the schema is complete.

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 uses a specific verb ('delete') plus a specific resource ('invoice'), which clearly separates it from siblings like wave_delete_customer, wave_delete_estimate, or wave_delete_invoice_payment. The adverb 'Permanently' adds a meaningful qualifier about the nature of the operation, though there is no explicit contrast with wave_update_invoice or any void/archive alternative.

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?

There is no when-to-use guidance, no prerequisites, and no named alternative among the many invoice siblings (update, clone, send). An agent must infer entirely from the name that this is the removal path rather than an update or reversal path.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description contributes real added context beyond that: it states the downstream consequence that the invoice is reduced back to unpaid by that amount, which helps an agent predict side effects. It stops short of saying whether the deletion is reversible, whether the invoice's status/history is recalculated, or what happens to linked transaction records.

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?

A single front-loaded sentence states the action and then the effect, with no boilerplate or repetition. Every clause earns its place; nothing could be removed without losing information.

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

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

For a one-parameter destructive tool with full annotation coverage and no output schema, the definition supplies the action, the target, and the accounting consequence — enough for correct invocation. The remaining gap is procedural context (irreversibility, permissions, how to obtain a valid payment ID) that an agent might want before firing a destructive call.

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 is a single required parameter and schema description coverage is 100%, with the schema already labeling it "Invoice payment ID". The description adds no format, sourcing guidance (e.g., obtain via wave_get_invoice_payment or wave_list_payments), or validation notes, 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 pairs the specific verb "delete" with the specific resource "recorded invoice payment" and adds the resulting state change. It is unambiguous, though it never explicitly contrasts with wave_delete_estimate_payment or wave_update_invoice_payment; the distinction is carried mainly by the tool name rather than the description.

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?

Usage is only implied: the word "recorded" hints that this removes an existing payment rather than a pending one, but there is no statement of when to delete versus correcting via wave_update_invoice_payment, nor any prerequisite (e.g., payment must exist, be unapplied). An agent must infer the selection criteria from the name alone.

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 destructiveHint=true and openWorldHint=true, but the description adds material context the agent would otherwise not have: the delete mutates books and account balances, it requires human confirmation, it is rejected for source-owned records, and it depends on an unofficial web-app API whose session can expire with a concrete remediation command. That is exactly the beyond-annotation disclosure this dimension rewards.

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 action and the destructive warning, then the failure modes, then the auth remedy — a sensible order with little wasted wording. The embedded container hostname and login command are verbose but actionable; the sentence could be tightened without losing meaning.

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 should cover behavior and side effects, and it does: mutation of books and balances, rejection paths, and auth prerequisites. The only real omission is what a successful call yields (no returned record, for instance), which an agent deleting an entity would reasonably want to know.

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 67%: businessId and expectedSequence are documented in the schema, while id is a bare string but self-evident. The description contributes nothing about expectedSequence, an optimistic-concurrency guard whose purpose (failing when the transaction changed since it was read) is worth reinforcing for a destructive call. Baseline 3 fits since the schema does most of the work.

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 first clause states a specific verb and resource ("Delete a transaction") and pins the semantics to the web app's own Delete behavior. An agent can immediately distinguish it from the many read/update siblings such as wave_get_transaction and wave_update_transaction 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?

It gives clear context: confirm with the user first, and expect a refusal for transactions that must be removed at their source (invoice payments, payroll). It also tells the agent what to do when the web session is missing or expired. It stops short of naming an alternative action for the refused cases (for example reversing via wave_update_transaction or deleting the source record instead), leaving that 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 cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=false). The description adds value by disclosing the 'regenerate' idempotent-ish behavior and the URL return value, which is meaningful given there is no output schema. It does not say whether the PDF is persisted or overwritten, whether generation is synchronous, or what permissions/state the estimate must be in.

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?

One short sentence with the action and result front-loaded and zero wasted wording. It is efficient, though borderline terse for a tool that mutates state (creates a PDF artifact).

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 tool with full schema coverage and no output schema, naming the returned URL is the key missing piece and it is present. However, prerequisites and side effects of PDF generation are not addressed, leaving gaps for an agent deciding when the call will succeed.

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 is a single required parameter with 100% schema description coverage, so the schema already documents estimateId. The description adds no syntax, format, or example for the ID, 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 ('Generate (or regenerate)') and a specific resource ('the estimate PDF'), and adds the useful detail that a URL is returned. It is clearly distinct from siblings such as wave_get_estimate or wave_send_estimate, though it does not explicitly name a boundary against any of them.

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 parenthetical '(or regenerate)' implies usage: call it when a PDF is needed for an existing estimate, including when one already exists. There is no explicit when-not guidance, no prerequisites (e.g., estimate must exist and be non-deleted), and no alternatives are named.

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, destructiveHint=false, and openWorldHint=false, so safety is fully covered. The description's valuable addition is disclosing the return payload shape (dual-currency balances, sequence number), which matters because there is no output schema. It stops short of noting error behavior for a missing id.

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?

A single compact sentence with zero filler, and the most informative fields are front-loaded. The fragmentary noun-phrase construction is slightly less clear than a verb-led sentence would be.

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 two-parameter read-only resource fetcher with rich annotations and a fully described schema, the only thing the structured fields cannot supply is the shape of the returned account, and the description covers exactly that. 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?

Schema description coverage is 100% and the schema already explains that businessId defaults to what wave_get_context reports. The description adds no parameter-level meaning, 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 is a noun phrase enumerating the fields of the returned object (type, subtype, normal balance, balances, sequence number) rather than stating a verb+resource action. Combined with the name wave_get_account the intent is inferable, but the text itself never says 'retrieves a single account by ID' and makes no reference to the adjacent wave_list_accounts tool.

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?

There is no guidance on when to use this versus wave_list_accounts or wave_get_reference, no mention of what happens when the id is unknown, and no note about the businessId default. The agent must infer the single-vs-list distinction from tool names alone.

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, non-destructive, and closed-world, so the safety profile is fully covered. The description's contribution is naming the payload fields, which is genuinely useful because there is no output schema, but it says nothing about failure modes (invalid or inaccessible businessId) or whether the default resolves silently.

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?

One front-loaded sentence with a colon-delimited field list; every element carries information for an agent with no output schema. Slightly dense as a fragment, but nothing is wasted.

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?

A simple single-record read with rich annotations and a fully documented parameter; the field enumeration compensates well for the absent output schema. Only the default-resolution behavior and error handling are left implicit, which is minor for this tool class.

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 parameter already documents that businessId defaults to whatever wave_get_context reports. The description adds no meaning beyond that — no guidance on when to omit versus pass explicitly — 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 ('Full details of one business') and enumerates the returned facets — address, contact info, currency, timezone, invoice-email capability, branding. That makes it clearly a single-record fetch rather than a list, though it never explicitly contrasts itself with wave_list_businesses.

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?

No when-to-use guidance at all: nothing about calling this before invoice/estimate creation to obtain branding defaults, and nothing about the fallback to the context business. The only hint of the default behavior lives in the schema, not the description.

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/non-destructive, and the description adds genuinely new behavior: it succeeds with no credentials at all and then acts as a setup guide, and it reports whether writes are enabled and what the public API cannot do. That is capability and failure-mode disclosure an agent cannot get from 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?

Three short sentences with the highest-value instruction ('Start here') front-loaded, followed by the return inventory and the no-credentials fallback. Every clause earns its place; nothing is repeated from the title.

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 carries the burden of explaining return values and does so by enumerating each field group. It also covers the authenticating and unauthenticated cases, which is the full decision surface for a zero-argument bootstrap 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?

There are zero parameters, so the baseline is 4. Nothing in the description needs to explain inputs, and it correctly devotes its space to return contents instead.

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

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

The description names a specific verb-and-resource pattern (returns connection context) and enumerates the exact contents: signed-in user, credential configuration, reachable businesses, default business, write enablement, and API limitations. The opening 'Start here' positions it clearly against the CRUD siblings like wave_get_business and wave_list_businesses.

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?

'Start here' is an explicit ordering instruction that tells the agent to call this before other wave_* tools. It also states the unauthenticated path ('works without credentials and then explains how to set them up'). It does not explicitly say when to call wave_list_businesses or wave_get_business instead, so it stops short of full alternative routing.

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

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

The annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable context beyond that by disclosing that deleted customers are still returned and flagged with deleted: true, although it does not cover not-found behavior or permission requirements.

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 two tight sentences with no filler. The included fields are front-loaded, followed by the important deleted-customer behavior.

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

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

For a simple single-customer lookup with two fully documented parameters and no output schema, the description supplies enough information about returned content and deleted records. Only edge-case behavior such as not-found handling is left implicit.

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 already explains both the id and businessId parameters. The description reinforces ID-based retrieval but adds no additional syntax or meaning beyond what the schema 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?

The description states that this returns one customer and enumerates the content included: address, shipping details, notes, and outstanding/overdue amounts. This clearly distinguishes it from a broader list operation, though it does not explicitly name wave_list_customers as the alternative.

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

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

The description implies retrieval by ID because it mentions deleted customers still being returned by ID, but it gives no explicit guidance on when to use this versus wave_list_customers or wave_get_context. No prerequisites or exclusions are stated.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description contributes the payload scope, which is useful because there is no output schema, but it says nothing about not-found handling, permissions, or whether the response is trimmed for large estimates.

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?

A single front-loaded sentence with no filler; every noun phrase names a returned component. It is a sentence fragment lacking a verb, but the information density is high and nothing needs trimming.

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 two-parameter read tool, the annotations cover safety, the schema covers inputs, and the description covers the returned payload in the absence of an output schema. The only real gap is the lack of pointer to wave_list_estimates for discovering an ID.

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%: 'id' is documented as the Estimate ID and 'businessId' explicitly states it defaults to the value wave_get_context reports. The description adds no additional meaning about either parameter, 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 identifies the resource ('One estimate') and enumerates the contents included in the payload (items, taxes, discounts, deposit settings, payments, acceptance history, attachments), which implicitly conveys a single-record fetch. The word 'One' distinguishes it from wave_list_estimates, though the verb itself is never stated explicitly.

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?

There is no explicit when-to-use guidance, no mention of the natural alternative (wave_list_estimates to find an ID first), and no statement of preconditions or error behavior. Retrieval context is only weakly implied by the singular noun phrase.

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, destructiveHint=false and closed-world scope, so the safety profile is fully covered by structured data. The description adds only the useful detail that the response bundles the parent estimate and that the record may be a payment, refund, or void — modest value beyond annotations, with no info on pagination, errors, or auth.

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?

It is a single short fragment with no wasted words, but it is under-written rather than concise — the parenthetical '(or refund/void)' is the only elaboration, and the missing verb makes it read as a title rather than a definition.

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 two-parameter read tool with complete annotations and full schema coverage, the minimum an agent needs is a clear verb and the return shape; the return shape is partially conveyed ('with its estimate') but the verb is absent and no output schema exists to compensate. Adequate but thin.

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 documented, including that businessId defaults to the value from wave_get_context, so the schema carries the semantics. The description adds nothing about the id format or prefix, but with a fully documented two-parameter schema the baseline of 3 is comfortably 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 phrase names the resource ('one estimate deposit payment') and hints at the return shape ('with its estimate'), but it is a noun fragment with no verb, so the action (fetch) is only inferable from the title and sibling naming convention. It does at least distinguish itself from payment-mutating siblings like wave_record_estimate_deposit and wave_delete_estimate_payment.

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?

There is no when-to-use guidance at all: no mention of when to call this versus wave_list_payments or wave_get_estimate, and no prerequisites. The agent must infer usage entirely from the tool name.

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, destructiveHint=false and closed-world scope, so the safety profile is covered. The description's list of returned components (line items, taxes, discounts, payments, reminders, PDF and customer view links) adds genuine value since no output schema exists, but it says nothing about behavior on an unknown or unauthorized ID, or whether any invoice state is excluded.

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?

A single short sentence with zero filler, but it is not front-loaded with an action verb, so the agent reads a payload list before understanding the operation. Slightly expanded to "Retrieve one invoice by ID; returns…" it would be both concise and scannable.

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 two-parameter read tool with rich annotations, this is close to adequate, and listing the returned components compensates in part for the absent output schema. However, the description never states the input contract (single invoice ID) or the failure mode, leaving meaningful gaps for an agent deciding between this and wave_list_invoices.

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 schema itself documents both parameters including the businessId default note pointing at wave_get_context. The description adds no meaning about the id parameter or the businessId fallback, 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?

The description is a noun-phrase fragment — "One invoice with line items, taxes, discounts, payments, reminders, PDF and customer view links" — with no verb; the retrieval action comes only from the title "Get invoice" and the tool name. It does implicitly distinguish itself from wave_list_invoices via "One invoice," but it never states explicitly that it fetches a single invoice by ID.

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

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

There is no when-to-use guidance, no mention of alternatives such as wave_list_invoices for browsing or wave_update_invoice/wave_delete_invoice for mutation, and no prerequisites or error conditions. The agent must infer usage entirely from the name.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description's only added behavior is the shape of the returned record (account, method, currency, processor), which is useful since no output schema exists, but it says nothing about not-found handling or scoping.

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?

A single compact sentence with no filler, and the most useful information (the returned record's contents) comes first. It is telegraphic rather than polished, but nothing is wasted.

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 two-parameter read with no output schema, the description at least signals what fields come back, which partially compensates for the missing return definition. It still omits error behavior and any routing context relative to the many payment-related siblings, so it is only minimally 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 description coverage is 100%, so both the required invoice payment id and the optional businessId default are already documented in the schema. The description adds no syntax, format, or sourcing guidance beyond that, which is the expected baseline when the schema does the work.

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 identifies the resource (one invoice payment) and enumerates the data it carries (account, method, currency, processor info), so the intent is inferable. However, it is a noun phrase with no explicit retrieval verb, and it does not distinguish this from nearby siblings such as wave_list_payments or wave_get_estimate_payment, leaving the agent to rely on the tool name.

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?

There is no when-to-use guidance at all: nothing says to call this when you have a payment ID, nor that wave_list_payments should be used to discover IDs first. No exclusions or alternatives are named despite a crowded sibling set of payment and invoice 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 declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so safety is covered. The description adds value beyond that by disclosing the response shape (all journal lines with account, debit, credit, description, sales tax), which matters because there is no output schema. It does not mention pagination or behavior when a transaction ID is absent.

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 short sentences with no waste. The returned content is front-loaded and the parameter-sourcing note follows immediately, which is the right order for an agent deciding whether to call it.

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 two-parameter read tool with no output schema, the description covers the essential missing pieces: what a record contains and where the required ID comes from. The businessId default is already handled in the schema, so nothing critical is absent, though a note on error behavior for unknown IDs would round it out.

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%: businessId is documented in the schema, but transactionId has no description there. The description compensates by stating that IDs come from wave_list_ledger_transactions, effectively explaining the origin and format of the one undocumented required 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?

The description names a specific resource and scope: a single transaction from the *imported ledger*, plus an enumeration of the journal-line fields returned. That distinguishes it reasonably from wave_get_transaction and wave_list_ledger_transactions, though it never explicitly contrasts itself with wave_get_transaction, which is the nearest ambiguous sibling.

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 a concrete sourcing rule — 'IDs come from wave_list_ledger_transactions' — which tells the agent how to obtain the required parameter. However, there is no when-to-use/when-not guidance relative to wave_get_transaction or wave_list_ledger_transactions, so the agent must infer that this is the detail-fetch following a list call.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, but the description still adds genuine context by disclosing that the response is hydrated with related accounts and default sales taxes. It does not state behavior for a missing or archived ID, but for a simple read that is a minor gap.

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?

It is a single front-loaded clause with no wasted wording, which is good. The trade-off is that it is so compressed that it reads as a fragment and omits the retrieval verb and any operational qualifiers.

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 two-parameter read tool with full schema coverage and complete annotations, this is close to adequate, and no output schema means return values needn't be detailed. What is missing is what happens on a nonexistent/archived product and what 'accounts' refers to, which an agent would need when interpreting results.

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 100% schema description coverage, the schema already documents both 'id' and 'businessId' including the default-to-context fallback, so the baseline is 3. The description adds no further meaning about whether the ID accepts a product key, a numeric ID, or a reference.

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 identifies the resource ('One product/service') and hints at the expanded payload ('with its accounts and default sales taxes'), and the singular 'One' implicitly contrasts with wave_list_products. However, it is a noun phrase rather than a verb+resource statement, so the retrieval action is only inferred from the name.

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?

There is no explicit when-to-use or when-not-to-use guidance and no mention of the sibling alternatives (wave_list_products, wave_update_product, wave_archive_product). The singular framing is the only cue that this is a single-record lookup rather than a list operation.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds that lists are paginated, but that is also visible in the page/pageSize parameters, and it does not say what a country lookup returns in shape terms or whether an invalid code errors versus returns empty.

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

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

Two sentences, front-loaded with the purpose and then the enumeration of kinds, with the pagination note trailing. The mid-sentence parentheticals make it dense but every clause carries information; no filler or restatement of the title.

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 five parameters, one enum and no output schema, the description covers the full kind vocabulary, the dependency between kind and code, and pagination behavior. The main residual gap is return shape per kind, but for a read-only lookup tool backed by an 80%-documented schema this is close to 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 80%, so the baseline is 3; the description earns an uplift by clarifying that kind=country returns one country together with its provinces/states and that kind=province resolves a single province by code. That adds interpretive value about what the code parameter selects, beyond the schema's terse 'Required for kind=country'.

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

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

The description names a specific verb-resource pair (get reference data) and then enumerates exactly which datasets are available: currencies, countries, country-with-provinces, province, account types and account subtypes. It also distinguishes itself from the account-related siblings by framing subtypes as inputs to wave_create_account rather than as account records.

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 states the intended usage context plainly — reference data needed to fill other tools' inputs — and explicitly ties account_subtypes to wave_create_account, which tells the agent when to reach for this instead of a list/CRUD sibling. It stops short of naming alternatives or exclusions (e.g. 'do not use for listing actual accounts; use wave_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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so the safety profile is covered. The description's one contribution beyond that is disclosing the shape of the response ('full dated rate history'), which is valuable given there is no output schema, but it says nothing about error behavior for missing or archived tax IDs.

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?

It is a single short sentence fragment with zero filler, and the salient detail (rate history) is front-loaded. Economy is good, though the terseness borders on under-specification rather than disciplined brevity.

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 two-parameter read tool with full schema coverage and strong annotations, the description covers the essentials at a minimum-viable level. The lack of an output schema is partly offset by the mention of dated rate history, but nothing explains failure modes or how this differs operationally from listing taxes.

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 already documents both the sales tax ID and the businessId default (falling back to the value from wave_get_context). The description adds no parameter meaning beyond this, 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 phrase 'One sales tax with its full dated rate history' identifies the resource as a single sales tax record rather than a list, which implicitly separates it from wave_list_sales_taxes, and it adds that rate history is included. However, it is a bare noun phrase with no verb, so the retrieval action is only inferable from the tool name and title rather than stated.

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?

There is no when-to-use guidance, no mention of the wave_list_sales_taxes alternative for enumerating taxes, and no statement that an ID is required to fetch a single record. The agent must infer the lookup workflow entirely from the name and 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 establish read-only, idempotent, non-destructive, open-world behavior. The description adds meaningful context beyond them: the unofficial web-app API dependency and the exact remediation if the session is missing or expired, plus the editable-field and review-status return content. It does not cover error handling beyond authentication.

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

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

Two sentences, purpose first and auth remediation second. The long enumeration in the first sentence is dense but necessary because there is no output schema; 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 read-only get-by-id tool with no output schema, the description covers the returned transaction structure and the session prerequisite. The schema handles parameter details, so no material context 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%, with descriptions for id and businessId; the description adds no additional parameter meaning such as format, defaults, or lookup behavior. Baseline 3 applies because the schema carries parameter semantics.

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 this returns a single transaction with its full set of lines and metadata, which is a specific resource and scope. It implicitly contrasts with wave_list_transactions by saying 'One transaction,' but it does not explicitly name that sibling or clarify its distinction from ledger transaction retrieval.

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 provides an authentication prerequisite (web session, login command) but no explicit when-to-use or when-not-to-use guidance versus wave_list_transactions or wave_get_ledger_transaction. Retrieval of one transaction by ID is implied by the description and 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 declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered. The description's only added behavior is the return content hint (address and contact details), which is real value given no output schema, but it says nothing about error behavior for an unknown ID.

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?

A single short phrase with zero filler and the payload information up front. It is efficient, though it is a sentence fragment rather than a structured statement of action and result.

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 two-parameter read-only getter with full schema coverage and rich annotations, the description is minimally adequate: it tells the agent what comes back. It omits what happens with an invalid or missing ID and does not point at wave_list_vendors for lookup-by-name, leaving small but real gaps.

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

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

Schema description coverage is 100% and both parameters (id, businessId) are documented in the schema, including the default-resolution note for businessId. The description adds no parameter meaning beyond that, 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?

"One vendor with address and contact details" conveys the resource (a single vendor) and the payload shape (address, contact details), but it is a noun fragment with no verb and never names the sibling it contrasts with, such as wave_list_vendors. An agent can infer retrieval from the title, but the description itself does not do the work.

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?

There is no when-to-use guidance and no routing to alternatives: nothing says to use wave_list_vendors when the ID is unknown or wave_get_context to resolve the default businessId. The singular "one vendor" only implicitly distinguishes it from the list 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 already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false; the description reinforces this with "never a mutation", which is the key safety signal for a free-form query tool. It adds real context beyond the annotations (raw unshaped return data, the wave://schema resource, pagination requirement, worked example), but says nothing about query size limits, depth/complexity caps, or error behavior when a query is malformed.

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 decision-relevant framing, then constraints, then schema pointer and example — a sensible ordering with no filler sentences. The opening clause is slightly convoluted ("reads the other tools do not shape the way you need"), but every sentence carries usable information.

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

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

For a two-parameter escape hatch with no output schema, the description covers what an agent needs: read-only scope, what comes back (raw data), where the API schema lives, and a concrete call shape. Missing only operational guardrails such as the query length limit and failure modes, which is why it is not a 5.

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 50%: only `query` is documented in the schema, and `variables` has no description at all. The description compensates meaningfully by showing a parameterized query document (`query($id: ID!){...}`), which implies how variables bind, and by pointing to wave://schema for field selection. It still omits the 20000-character cap on `query` and any statement about how `variables` is passed.

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 ("run one GraphQL query ... against Wave's public API") plus the explicit scope boundary "never a mutation". The framing as an "escape hatch for reads the other tools do not shape" immediately distinguishes it from the ~70 shape-specific sibling tools (wave_list_customers, wave_get_invoice, etc.).

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 a clear selection rule: use this only when the purpose-built tools do not shape reads the way you need, and never for mutations. It also supplies two mandatory invocation practices (select only needed fields; always pass page/pageSize on connections) that an agent would otherwise get wrong.

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: it discloses that an earlier import for the business is replaced (concretely explaining destructiveHint=true), that nothing is sent to Wave (reinforcing openWorldHint=false and clarifying the network/auth posture), and that the ledger is stored locally with mode 600 permissions. These are exactly the side-effect and data-safety facts an agent needs before invoking a destructive write.

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?

Five dense, front-loaded sentences: what it does, why it exists, how to get the file, what to pass, and what the side effects are. No filler, and the destructive caveat lands before an agent would act.

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 two-parameter destructive import with no output schema, this covers acquisition, argument form, scope, and side effects. The only gap is the result: nothing about what is reported back (transaction count, validation failures on a malformed CSV), which an agent would want after a replace-the-ledger operation.

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 earns above that by clarifying that the path must resolve on the machine running the server and that either the .zip or the inner accounting .csv is acceptable. It says nothing about businessId, but the schema already documents that default fully.

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 ("Load the full transaction journal from Wave's Data Export") plus the downstream purpose (listing and date-range reports), and explains why this path exists at all ("Wave's public API cannot read transactions"), which cleanly separates it from wave_list_transactions and wave_list_ledger_transactions. An agent can pick this 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?

Gives explicit trigger conditions and even operational steps to obtain the input (Settings → Data Export → Accounting CSV → emailed 24h link). The routing statement that this is the supported ingestion path is a strong when-to-use signal, but there is no explicit "when not to use" — e.g. no note that manually created transactions already live locally and don't require an import.

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, so the safety profile is covered structurally. The description adds that returned accounts carry current balances, which is useful behavioral context, but says nothing about pagination behavior, how archived accounts are handled, or what the focused default (isArchived false, detail=summary) implies for output volume.

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

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

Two sentences, front-loaded with the purpose before the filter recipes, and no filler. The semicolon-separated recipe list is dense but each clause corresponds to a distinct lookup the agent may need.

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 9-parameter list tool with no output schema, the description covers the conceptual core (what the list contains, how to filter for the common cases) while the schema documents the plumbing (page/pageSize/nextPage, detail, search, isArchived). Minor residual gap: the description never mentions paging or the summary-vs-full output distinction, which matters for a paginated read.

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 documents parameters at roughly 67% coverage, listing enum values without explaining what they mean in business terms. The description bridges that gap by mapping real-world concepts (bank account, credit card, expense category, income category) onto specific types/subtypes combinations, which is meaning the enum list alone cannot convey.

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 the chart of accounts with current balances" — so the agent knows exactly what is returned (account records plus balances). It does not, however, distinguish itself from nearby siblings such as wave_get_account or wave_list_ledger_accounts, which an agent could plausibly confuse it with.

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?

Strong practical guidance via concrete filter recipes: bank accounts are types=[ASSET] subtypes=[CASH_AND_BANK], credit cards subtypes=[CREDIT_CARD], expense types=[EXPENSE], income types=[INCOME]. This tells the agent how to accomplish common lookups, but there is no explicit when-not-to-use or pointer to alternative tools for account lookup.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds two facts beyond that: results are paginated and scoped to the credential's accessible businesses. It does not say whether archived businesses appear by default or what a business record contains.

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?

A single sentence with no filler; scope and pagination are both front-loaded. Nothing in it could be removed without losing information.

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

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

For a zero-required-parameter list tool with rich annotations, a fully documented schema, and no output schema, this is nearly sufficient. The one remaining gap is that the default inclusion of archived businesses is only discoverable by reading the isArchived schema entry, not the description itself.

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 all three parameters (page, pageSize, isArchived) carry their own inline descriptions, including the default-both behavior for isArchived. The description adds no parameter-specific meaning beyond the schema, 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 and resource ("List the Wave businesses") and adds the scope constraint that results are limited to what the credential can access. It does not name the sibling wave_get_business or explain the list-vs-get relationship, so differentiation is left to inference.

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?

Usage is only implied: the credential-scoped listing suggests this is the entry point for discovering business IDs before calling wave_get_business, but no when-to-use or when-not-to-use condition is stated. No alternative tool is named.

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, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral content beyond that: the response includes outstanding and overdue balances, exact-match semantics for email, and the notable performance trait that search scans the full list while filters do not.

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

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

Two sentences, front-loaded with purpose and return content, followed immediately by filter guidance. Every clause carries information and nothing is repeated.

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 10-parameter read tool with no output schema, the description covers purpose, returned data and filter strategy adequately, and the schema handles the rest. A small gap remains: the summary-vs-full detail tradeoff and pagination are only implied via schema, and the default business resolution is not hinted at.

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 90%, so nearly every parameter is already documented, and most of the description's parameter text (exact email, archive state, modification time) restates the schema. The one marginal addition is steering agents to search for name substrings, but it does not explain detail, sort, or pagination semantics beyond the schema.

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

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

The description states a specific verb and resource ('List customers') and adds what the listing surfaces ('outstanding and overdue balances'), which is useful since there is no output schema. It does not explicitly distinguish itself from wave_get_customer or other list siblings, but the list-vs-get distinction is implicit in the name.

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 concrete guidance on which filters to use ('exact email, archive state or modification time') and warns to prefer search only for name substrings, which is a genuine usage nuance. However, there is no explicit when-to-use-this-vs-alternative guidance naming wave_get_customer for single-record lookups or wave_list_invoices for related data.

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 the safety profile (readOnly, idempotent, non-destructive), so the description's job is to add operational detail — and it does, disclosing that detail="full" expands into line items, deposit payments and acceptance history, and that full results page at a maximum of 25. That page cap is non-obvious and not derivable from the schema, which advertises pageSize up to 100.

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 dense sentences, front-loaded with the primary purpose and with zero filler. The trailing parenthetical "(pages of at most 25)" is slightly ambiguous about whether it caps pages, items per page, or line items, which costs a point.

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 14-parameter list tool with no output schema, the description covers the return-shape question reasonably well but leaves filtering and sorting behavior entirely to the schema. An agent still has to open the schema to learn that filters exist and how pagination interacts with detail mode.

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 71%, setting a baseline of 3. The description does add real meaning for the detail switch (what "full" actually returns) and the 25-item full-mode page ceiling, but it says nothing about the many filters (status, currency, customerId, estimate date range, amountDue, sort) that an agent must learn from the schema alone.

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

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

States a specific verb and resource ("List estimates") and disambiguates the vocabulary by equating estimates with quotes, then names the fields surfaced (totals, deposit state, status). It is clearly the collection-level reader versus wave_get_estimate, though it never names that sibling explicitly.

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?

Usage is only implied: an agent can infer this is for browsing/filtering estimates rather than fetching one by ID or mutating one. There is no explicit when-to-use or when-not-to-use guidance relative to wave_get_estimate, wave_list_invoices, or the estimate mutation siblings.

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, non-destructive, so the safety profile is covered. The description still adds real behavioral context beyond the structured fields: detail="full" expands to line items and payments and caps pages at 25, a constraint that is not expressed in the schema's pageSize maximum of 100. It does not discuss rate limits or result ordering beyond what the schema declares.

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

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

Two sentences, no filler, with the returned fields front-loaded and the filters grouped into a single enumeration. The one behavioral caveat (page size under full detail) is placed where it is needed, right after the parameter it modifies.

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 15-parameter list tool with no output schema and no required parameters, the description gives enough to select filters and understand the summary-vs-full tradeoff, and annotations handle safety. The remaining gap is that a few filters (amountDue, sort) are never mentioned, though the schema documents them.

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 80%, so the schema already carries most parameter meaning and the baseline is 3. The description adds a little — the parenthetical gloss on sourceId's origin and the 25-item page cap under full detail — but leaves amountDue, sort, businessId, page and pageSize entirely to the schema. Adequate rather than additive.

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 invoices") and immediately names the fields returned (totals, amount due, status), which cleanly distinguishes it from single-invoice readers like wave_get_invoice in the sibling set. It stops short of explicitly naming the sibling it is not, which keeps it at 4 rather than 5.

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 filter inventory implicitly tells the agent this is the tool for querying invoices by status/customer/date/number/currency/source, and the note that detail="full" adds line items and restricts pages to 25 hints at when to accept the extra cost. There is no explicit when-to-use vs. when-not guidance and no pointer to wave_get_invoice for single-record retrieval.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds useful payload context (type derivation source and line counts) that helps the agent judge whether the result is worth fetching. It says nothing about pagination behavior, empty-ledger cases, or ordering, which the schema only partially covers via the 'use nextPage' note on the page parameter.

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

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

Two sentences, both front-loaded with the payload description first and the practical follow-up second; nothing is padded. Minor deduction: 'account_transactions reports' is an opaque reference — no tool by that name appears in the sibling list, so the phrase costs a little clarity without a resolvable target.

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 carries the burden of describing return values and does so adequately (type, provenance, line counts). Combined with the schema's pagination documentation and the annotations' safety profile, an agent has what it needs to call the tool correctly. Only the relationship to wave_list_accounts remains unstated.

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 three parameters (page, pageSize, businessId) have full schema descriptions at 100% coverage, so the baseline of 3 applies. The description adds no parameter-level meaning — it does not say, for example, how pageSize interacts with the line counts or what the businessId default means in a multi-business context beyond what the schema already states.

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 resource (accounts appearing in the imported ledger) plus the returned content: type, type provenance (Wave chart of accounts vs. export labels), and line counts. That is more than a restatement of the name. It stops short of explicitly distinguishing itself from the sibling wave_list_accounts, leaving the agent to infer the ledger-vs-chart-of-accounts split from the phrase 'imported ledger'.

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 second sentence gives downstream guidance — reuse the returned names or IDs as filters for wave_list_ledger_transactions and account_transactions reports — which is genuine workflow context. However, there is no statement of when to call this tool versus wave_list_accounts, and no prerequisites or exclusions, so call-selection is still implied rather than specified.

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, so safety is covered; the description adds context those annotations cannot: it works offline against an imported snapshot, results are newest-first by default, and each row carries the bank/card amount (or journal total), its categories, and the transaction ID. It does not restate pagination or cursor mechanics, but nothing here contradicts 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 offline/live distinction is front-loaded and every sentence carries content rather than filler. The paragraph of filters is denser than ideal but stays scannable and wastes little space.

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 15 optional parameters and no output schema, the description takes on the return-value burden by describing the row shape and the follow-up call for details. Combined with the data-source caveat and default ordering, an agent has everything needed to call it correctly.

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

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

Schema coverage is 60% across 15 parameters, so the description must compensate and largely does by grouping the filter dimensions (date range, account by ID or name, text, customer, vendor, amount, direction, uncategorized only) and clarifying that account accepts a name or an ID. It stops short of explaining the direction or sort enum values and leaves vendor/customer/amount params to bare schema names.

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 and search ledger transactions) plus the exact data source: an imported Data Export snapshot via wave_import_ledger. It explicitly distinguishes itself from wave_list_transactions (live data) and enumerates the record types included, so an agent can separate it from every sibling 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?

Gives an explicit alternative and the condition that selects it: use wave_list_transactions for live data, this one for offline snapshots. It also names wave_get_ledger_transaction for drilling into a single row, covering both the when and the next step.

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

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

Annotations already establish readOnly, idempotent, non-destructive, closed-world behavior, so the description's job is to add context — and it does, disclosing the default newest-first ordering, that totals are included, and the hard API scope limit on which transaction records are readable. It does not mention pagination behavior beyond the schema's offset field, 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?

Three tight sentences, front-loaded with what is returned before the scope limitations and filters. No filler, though the scope-limitation sentence is dense and could have been split for scanability.

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 an 8-parameter read tool with no output schema, the description covers what is returned ('with totals'), ordering, and the filter surface, which is enough to call it correctly. The main gap is the absence of any note on pagination/nextOffset behavior or a pointer to the sibling for non-payment transactions.

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 63%, and the description compensates by explaining that filtering is by payment date range and customer, and by mapping the undescribed 'kind' enum values to plain language ('invoice payments and estimate deposits'). It adds little about sort, limit or offset, but those are already documented 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 names a specific verb and resource ('List money received: invoice payments and estimate deposits'), enumerates the exact record kinds returned, and states ordering and totals. It also distinguishes itself from other transaction-reading siblings by declaring that bank/card transactions, expenses and API-created money transactions cannot be listed.

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

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

It gives clear conditions for use (invoice payments and estimate deposits only) and explicit exclusions for what this tool will not return, which steers the agent away from misusing it. It stops short of naming the sibling tool to use for the excluded transaction types (e.g. wave_list_transactions), so the routing is implied rather than explicit.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's added value is the default filtering behavior: archived records are excluded unless isArchived=true. That is a genuinely useful disclosure an agent could otherwise get wrong. It stops short of describing paging/response behavior, which matters for a list 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?

Two sentences, zero filler, with the resource identified first and the archived-visibility caveat front-loaded at the end where it is easy to scan. Nothing is repeated unnecessarily.

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

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

For an 11-parameter read tool with no output schema, the description covers purpose, key returned fields, and the archived default, but leaves the response shape and pagination contract (page/nextPage, pageSize cap) to the schema alone. It is adequate but not fully self-sufficient for an agent that must page through results.

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 every parameter including isArchived, detail, search, and the modifiedAt bounds is already documented in structured data. The description only restates the isArchived default and the returned field categories; it adds no new meaning about parameter interplay (e.g. how search interacts with paging) 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?

"List products/services" is a specific verb+resource, and the parenthetical explains the domain role (the items invoice and estimate lines must reference) plus the fields returned (price, income/expense accounts, default sales taxes). It is clearly distinct from wave_get_product / wave_create_product / wave_update_product by name and verb, though it never names a sibling to route against.

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?

Usage is implied rather than stated: the agent learns this is the catalog of items that invoice/estimate lines must reference, which suggests when to call it, and the archived default is flagged. There is no explicit when-to-use vs. alternatives (e.g. wave_get_product for a single item), no mention of when search/paging is preferred over a full scan.

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, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds resource-specific behavior (rate as a fraction, full detail returns dated history), but says nothing about pagination, pageSize limits, or what the summary mode clips — gaps an agent may care about.

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 short sentences, zero filler, with the most consequential clarification (rate format) placed first and the non-default detail mode second. Nothing is repeated from the schema or annotations.

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 an 8-parameter read-only list tool with full schema descriptions and no output schema, the description covers the resource-specific quirks well. Remaining omissions (pagination flow, default business scoping) are already handled by the schema, so nothing essential is missing, though a note about large-list paging would strengthen 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, but the description goes beyond the schema by explaining that detail="full" specifically yields the dated rate history for this resource, which the generic schema text does not convey. Rate-fraction notation also adds interpretive meaning the schema lacks.

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 sales taxes") and immediately clarifies the rate representation (0.13 = 13%), which is the key ambiguity for this resource. It does not explicitly distinguish itself from the sibling wave_get_sales_tax or wave_list_sales_taxes filters, so it stops short of a 5.

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?

Usage is only implied: the description hints that detail="full" is the way to get history, but never says when to prefer that over wave_get_sales_tax or how to combine it with the search/filter parameters. There are no explicit when-not conditions or named alternatives.

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