Billstride

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

Goes well past the annotations: exact-match uniqueness on the trimmed company name, duplicate calls are rejected and leave no record, DATEV debtor number auto-assigned and not choosable, VAT ID not validated, no invoice created, no email sent. The rejection-on-duplicate behavior is consistent with idempotentHint=true and destructiveHint=false.

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

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

Purpose is front-loaded in the first clause, then each following sentence delivers a distinct behavioral fact (uniqueness, numbering, validation, scope boundary, side-effect boundary). No sentence merely restates the tool name or 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?

Covers creation semantics, duplicate handling, and side-effect boundaries for a 9-parameter mutation tool with no annotations beyond hints. The notable gap is the return value: with no output schema, it never says whether the response contains the customer ID or the assigned DATEV debtor number, which an agent would likely need for follow-up calls.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real meaning on top by specifying that companyName is trimmed, exact-compared and unique in the account, and that vatId is stored verbatim without a format check. Address sub-fields (street, city, state, postalCode, country, addressLine2) are only summarized as 'an address' and left 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?

States a specific verb and resource (create a customer record) plus the minimum required input and which fields are optional. It also explicitly separates itself from create_invoice, so an agent can route without opening the sibling's 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 a concrete when-to-use case ('store a client before their first invoice') and an explicit when-not/alternative: create_invoice does not require this tool first, because it creates the customer record itself. That is exactly the routing information an agent needs between two overlapping 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?

The description adds rich behavior beyond the annotations: drafts are free and editable/deletable, finalized invoices spend credits, cannot be deleted, and low-balance failures are not refunded. It also discloses side effects such as automatic customer creation, no emailing, and duplicate invoices on repeated calls, all consistent with the destructive and non-idempotent hints.

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

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

The description is front-loaded and mostly earns its length because the tool is complex and has significant financial side effects. However, a few passages repeat schema details such as unit price and VAT basis-point examples, which slightly reduces concision.

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 21-parameter creation tool with no output schema, the description is unusually complete: it covers billing behavior, draft/final modes, date defaults and format risks, customer-record side effects, no emailing, and duplicate-call behavior. An agent has enough context 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 100%, so the baseline is 3, but the description adds useful semantics around date formats and parsing edge cases, defaults from sender settings, and unitPrice versus unitPriceCents. Some parameter information duplicates the schema, but the date-format caveats are genuinely additional meaning.

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: creates a new invoice from recipient, line items and discounts. It explicitly distinguishes this from the sibling create_invoice_from_previous, so an agent can route correctly without inspecting schemas.

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

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

It clearly states when to use this tool versus the alternative: new invoice from scratch, or create_invoice_from_previous for repeat work. It also explains the critical draft-versus-finalized mode choice and its cost consequences.

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 goes well beyond the annotations by disclosing that drafts are free, final invoices spend credits, charges are not refunded, low balances and missing prior invoices cause failure, and a customer record may be created as a side effect. It also states no email is sent and each call creates another invoice, which is exactly the behavioral context needed for a non-idempotent, destructive mutation.

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

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

The description is front-loaded with purpose and then proceeds through usage, override behavior, date handling, cost, and side effects in a logical order. It is fairly long, but most details are justified by the tool's complexity; the date-parsing edge cases are useful though slightly verbose.

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 12-parameter mutation, the description covers costs, failure modes, side effects, date formatting, and override rules thoroughly. It does not describe what the tool returns, and because there is no output schema, that is a remaining gap for an agent that needs to know the result of the 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 coverage is 100%, so parameter documentation is already strong. The description still adds meaningful semantics by listing which fields can be overridden, stating that recipient details and discounts cannot, explaining the date format dependency on get_sender_settings, and clarifying the draft/final effect of isDraft.

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: it creates a new invoice by copying the most recent invoice for a named recipient. It clearly distinguishes this from creating from scratch or updating an existing invoice by explaining that recipient details and discounts are copied and not overridable.

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 clear use case: recurring work such as repeating last month's invoice with different hours. It also points to update_invoice for later changes to copied fields, but it does not explicitly contrast this tool with siblings like create_invoice or duplicate_invoice, so the alternative-selection guidance is not complete.

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 irreversibility, the precise rejection rule and its rationale (debtor number anchoring in export_datev), the referential side effect on invoices and recurring templates, and the absence of email side effects. The 'repeating the call deletes nothing further and returns an error' note is consistent with idempotentHint=true (state unchanged) and adds real value.

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?

Purpose is front-loaded and most sentences carry distinct operational information, but the description runs to eight sentences and includes a marginally relevant closer ('It does not email anyone') plus a lengthy embedded rationale. Slightly tighter phrasing would lose nothing.

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

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

Covers preconditions, side effects, repeat-call behavior, and error semantics for a destructive tool with no output schema. The only gap is that it never states what a successful call returns, though for a delete that omission is minor.

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 explains the id ('as returned by list_customers'), so the description adds nothing beyond 'chosen by id'. Baseline 3 is appropriate when the schema carries the parameter meaning.

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 ('Permanently deletes one customer record') with explicit scope ('one', 'chosen by id'). The domain is clearly separated from siblings like delete_invoice, and the opening sentence alone tells an agent exactly what the tool does.

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 when-to-use ('a client that was entered by mistake or is no longer needed') and, more importantly, when-not conditions: customers with finalized invoices are rejected, while those with only drafts or no invoices can be deleted. The eligibility boundary is unambiguous.

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 destructiveHint=true: states irreversibility, the cascade to line items and PDFs, the exact rejection conditions (linked email, reminder, payment, credit note; finalized invoices are cancelled via credit note instead), and that the import credit is not refunded. Adds that no email is sent, closing a common side-effect question.

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

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

Front-loads the action and cascade, then consequences, then eligibility rules — every sentence carries distinct information. It is dense but slightly long; the 'does not email anyone' line is a useful but minor addendum.

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

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

For a single-parameter destructive tool with no output schema, an agent has everything needed: what is destroyed, what blocks deletion, what happens to finalized invoices, and that the operation is irreversible.

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

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

Only one parameter, 'id', already fully documented in the schema at 100% coverage. The description adds no format, sourcing, or lookup guidance for the ID, so it neither helps nor harms beyond the schema 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?

States a specific verb and resource (permanently deletes one invoice) plus the cascade scope (line items, uploaded PDFs). This is immediately distinguishable from sibling mutators like update_invoice or delete_customer.

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

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

Gives explicit when-to-use cases (a draft the user no longer wants, an unused import) and precise preconditions for rejection. It does not name sibling alternatives such as update_invoice or a cancellation path, but the usage conditions are unambiguous.

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 the copy is always a draft, costs no credits regardless of the original's status, has no invoice number, is non-idempotent in a user-visible way ('repeating a call that succeeded leaves a duplicate'), and triggers a customer-record creation side effect without emailing anyone. These are exactly the traits the annotations cannot convey.

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

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

Front-loaded with the core action and effect, followed by alternatives and caveats in a logical order. It is dense and sentence-heavy, but essentially every sentence carries non-redundant operational 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 single-parameter mutation with no output schema, the description covers the outcome (draft, unnumbered), cost, idempotency behavior, side effects, and follow-up tool. Nothing an agent needs to call it correctly is missing.

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

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

Only one parameter, and the schema already documents it at 100% coverage ('Invoice ID to duplicate'). The description's 'chosen by id' adds no syntax or format detail beyond the schema, so the baseline 3 for high coverage is appropriate.

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

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

States a specific verb and resource ('Creates a draft copy of one existing invoice') plus the exact scope of what is copied (recipient, line items, discounts, dates, sender details). It explicitly contrasts with the sibling create_invoice_from_previous, so an agent can distinguish the two 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 explicit routing: use this to reuse a specific invoice, use create_invoice_from_previous to copy a recipient's latest invoice with field overrides. It also names update_invoice as the follow-up for setting a number and finalizing, and warns that repeats create duplicates.

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

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

Annotations declare non-read-only, idempotent, non-destructive, and the description goes well beyond them: it discloses the side effect of creating debtor-number customer records and linking invoices, confirms nothing is overwritten/deleted, confirms repeat calls add nothing (consistent with idempotentHint), and clarifies it does not email. That is exactly the extra context the annotation bar asks for.

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 result, then prerequisites, then side effects; each sentence carries distinct information. The first sentence is dense with clauses 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?

Covers purpose, preconditions, side effects, idempotency, and return payload (ZIP with counts and warnings) despite having no output schema; an agent has everything needed to decide and call correctly.

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

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

Schema coverage is 100%, so baseline is 3; the description adds real value by clarifying both are ISO dates (YYYY-MM-DD) and that the input date format is independent of the sender's format, and that only finalized invoices in the range are exported.

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 (builds a DATEV export), the exact resource (booking batch and master data CSV files), the scope (finalized invoices between from and to), and the return format (base64 ZIP with counts and warnings). No sibling tool does anything similar, so an agent can differentiate it immediately.

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

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

Explicitly says when to use it ('when the user or their tax advisor needs the bookkeeping export') and states hard preconditions (German sender address, DATEV consultant and client numbers in sender settings), which even points an agent at get_sender_settings to verify.

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 openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations by specifying the exact return contents and units (integer cents, formatted amount, free invoices left). It does not mention auth or rate limits, but for a simple read-only balance lookup that is not a major 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?

Two sentences, front-loaded with the return values and followed by the intended usage. Every sentence earns its place; there is no repetition or filler.

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

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

There is no output schema, so the description must explain return values, and it does so by naming all three returned pieces of information and their units. For a zero-parameter, read-only tool, nothing essential is missing.

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

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

The tool has zero parameters, so parameter semantics carry no burden. The baseline for zero parameters is 4, and the description correctly does not waste space describing inputs.

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 (returns the account's prepaid credit balance) and explicitly lists the returned values: integer cents, formatted amount, and free invoices left. This is clearly distinct from all sibling invoice/customer tools, which manage records rather than account credit.

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 usage context: 'Use it before finalizing an invoice to check the charge can be covered.' That is clear guidance for when to call it. It does not name exclusions or alternatives, but no sibling tool provides the same balance information, so the omission is minor.

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

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

Annotations already declare read-only/idempotent/non-destructive, so the safety profile is covered, and the description still adds real behavior: drafts are ignored, currencies are summed without conversion, and a no-finalized-invoice case raises an error. The only missing piece is the error shape or empty-result handling, which is minor.

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

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

Front-loads the summary contents, then appends caveats in a compact block with no filler. The lead sentence is long but every clause is load-bearing; only slight tightening would improve 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?

With no output schema, the description fully enumerates the return fields (count, totals, dates, top line items with latest price, email count) and flags the error case, which is everything an agent needs to call and interpret 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% and the single parameter is documented as an exact match, so the description's "(exact company name)" merely restates the schema. Baseline 3 applies; no extra format or edge-case guidance (e.g. casing, whitespace) is added.

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 ("Summarizes the finalized invoices for one client") and enumerates exactly what the summary contains, so an agent can tell it apart from get_customer, get_balance, or get_revenue_summary without inspecting schemas.

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

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

Gives clear usage contexts: "answer questions about a client" or "pick prices for their next invoice." It does not name explicit alternatives or when-not-to-use cases, but the intended situations are concrete.

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

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

Beyond the annotations' readOnly/idempotent profile, it discloses non-obvious behavioral caveats: the invoice count and list can be incomplete, they include drafts and credit notes, and linking happens by exact company name at create/edit time. This is exactly the kind of limitation an agent could not infer from structured fields.

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

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

Front-loaded with the return payload, then usage, then the completeness caveat — the ordering is logical and nearly every clause carries information. It runs slightly long, and the explicit 'Read-only.' sentence largely restates the 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?

With no output schema, the description carries the full burden of describing return shape, and it does so field-by-field including the embedded recent-invoice list. An agent has enough to decide, call, and interpret results correctly.

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

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

Schema coverage is 100% and the schema already states the id comes from list_customers, so the description's main addition is the negative constraint that lookup by name is impossible. That is useful but the parameter itself needs no further syntax or format 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?

States a specific verb and resource ('returns one customer record in full') and enumerates exactly which fields come back plus the embedded invoice count and 10 most recent invoices. This clearly distinguishes it from list_customers, get_invoice, and list_invoices.

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

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

Names two concrete downstream uses: supplying recipient fields for create_invoice (explicitly noting that tool takes fields, not a customer id) and checking stored values before update_customer. It also names the precursor (list_customers) and gives an alternative path (list_invoices filtered by recipient name) for completeness.

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

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

Annotations already declare readOnlyHint=true, so 'Read-only' is redundant but not contradictory. The description adds real value by warning that delivery and open times depend on the email provider and can be missing, setting correct expectations for the agent.

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 what is returned, then when to use it, then the caveat. Every sentence earns its place with no repetition.

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

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

No output schema exists, so the description compensates by naming the returned fields. Combined with the usage guidance and the provider caveat, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100% and the single invoiceId parameter is fully documented in the schema. The description reinforces that history is scoped to 'one invoice' but adds no syntax or format detail beyond that, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Lists the emails sent for one invoice') and enumerates the returned data (recipient, subject, message, sent/delivered/opened/bounced times). This clearly separates it from send_invoice and send_reminder among the siblings.

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

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

Gives an explicit use condition: 'check whether an invoice reached the customer before sending it again or sending a reminder.' It implies the alternative actions without naming the sibling tools directly, which leaves a small gap but is still clear guidance.

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

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

Annotations already cover read-only, idempotent, non-destructive, and closed-world behavior, and the description adds useful disclosure about the full return contents. The note that it cannot look up by invoice number adds a concrete behavioral limitation beyond structured fields.

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

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

The description is front-loaded with the return contents, then gives usage context and constraints in two short sentences. Every sentence carries actionable information with no repetition.

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

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

For a simple one-parameter read-only tool, the description covers purpose, return shape, usage, ID provenance, and a key limitation. With annotations and schema already clear, nothing important for correct invocation is missing.

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

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

Schema coverage is 100%, so the parameter's base meaning is already documented. The description still adds value by saying the invoice id should come from list_invoices and that invoice-number lookup is not supported.

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: returns one invoice in full, and enumerates the returned contents (sender/recipient details, dates, totals, line items, discounts, payments). It is clearly distinguishable from list_invoices and update_invoice by naming both siblings and its scope.

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

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

Explicitly says to use it to review an invoice or to fetch complete current values needed by update_invoice, and specifies that the id comes from list_invoices. It also states a clear exclusion: it cannot look up by invoice number.

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?

Adds substantial context beyond the readOnlyHint=true annotation: the link expires in 15 minutes and requires no sign-in, so anyone holding it can download; drafts come back watermarked DRAFT; imported invoices return the uploaded PDF; and missing required e-invoice fields produce a named error instead of a link. Nothing contradicts the annotations, and 'nothing is stored or sent' reinforces the read-only profile.

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

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

The critical fact (a link, not a file) is front-loaded and the format explanation follows in a logical order. The final sentence about recipient and sender field mutability drifts into update_invoice territory and does not help an agent call this tool, so it does not fully earn 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 two-parameter, no-output-schema tool, the description covers what is returned (a time-limited link), what each format yields, how drafts and imported invoices differ, and what happens on error. An agent has everything it needs to call this correctly and set user expectations.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: pdf is the default, zugferd embeds e-invoice data in the PDF, xrechnung is e-invoice XML, and the e-invoice options only work on finalized invoices. The trailing detail about mutable recipient fields versus fixed sender details is tangential but still clarifies the domain state behind the format choice.

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 (returns a download link for an invoice) and immediately disambiguates output type: a link, not the file, with three concrete formats. It does not name its closest sibling (get_invoice_preview) or contrast with get_invoice, so the differentiation is implicit rather than explicit.

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 clear usage triggers: when the user wants to see or save the document, check a draft before finalizing, or needs an e-invoice for a business customer. It also states a hard constraint (e-invoice formats require a finalized invoice), but never names an alternative tool for the preview/metadata cases, leaving routing 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?

Goes well past the annotations: discloses output format and approximate dimensions, default-page behavior, that an out-of-range page is rejected with the page count, the DRAFT watermark on drafts, and per-account rate limiting with a wait time returned on rejection. The read-only claim is consistent with readOnlyHint rather than a restatement of it, since it specifies nothing is stored or sent.

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

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

Front-loads what the tool returns and what it is not, then layers usage, edge behavior, quality caveat, and rate limiting. Every sentence carries information, though the read-only sentence is largely redundant with readOnlyHint and the whole is near the upper bound of useful length.

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

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

For a two-parameter, no-output-schema, read-only preview tool, the description covers return medium, sizing, defaults, error behavior, draft watermarking, fidelity limits, and rate limiting. An agent has everything needed to call it correctly and to know when not to.

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

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

Schema coverage is 100%, so baseline is 3, and the description earns above that by adding runtime semantics the schema cannot express: page defaults to the first page, and a page past the end is rejected and the page count is returned (useful because 'page' is capped at 500 in the schema, not at the real count). It does not describe the id format, but the schema already labels it.

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

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

States a specific verb+resource (returns one page of an invoice as a JPEG image) and immediately names its distinguishing scope: it is a rendered page, not the document. It explicitly separates itself from get_invoice_pdf (the file to save) and get_invoice (the exact values), so an agent can route without opening sibling schemas.

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

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

Gives the use case ('look at how an invoice or a draft is laid out'), the alternative for saving/passing on (get_invoice_pdf), and the alternative for exact values (get_invoice). The trade-off driving the choice — reduced image, small print hard to read — is spelled out rather than implied.

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 openWorldHint=false. The description adds substantial behavioral context beyond annotations: it counts finalized invoices by invoice date, excludes drafts and imported invoices, does not indicate payment status, and sums different currencies unless a filter is given.

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, front-loaded sentence that covers purpose, outputs, and key caveats without filler. It is dense but every clause contributes; structure could be slightly improved by splitting the long sentence, but it remains clear.

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 lists the return contents explicitly (total, monthly breakdown, top ten clients) and covers the safety profile via annotations. It also discloses important limitations (excludes drafts/imported, payment status unknown, currency mixing), leaving no major gap for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by clarifying currency aggregation behavior ('adds different currencies together unless a currency filter is given') and reaffirming the default year, which is important for interpreting results.

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

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

The description specifies the verb ('Summarizes'), the resource ('invoiced revenue'), the scope ('one calendar year'), and the exact outputs ('total in cents, a month-by-month breakdown and the ten largest clients'). It also names the use case ('questions about turnover'), making it easy to distinguish from siblings like get_balance or get_client_insights.

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 clear usage context ('Use it for questions about turnover') but does not name alternatives or explicit when-not conditions, such as using get_balance for outstanding amounts. The exclusions it provides are about data scope, 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 readOnlyHint/idempotentHint/openWorldHint=false, and the description's 'Read-only' restates that. Its real value is the pre-condition: it errors for accounts that haven't finished onboarding in the web app, a failure mode not captured by any annotation, plus the note that these values are the defaults applied to invoice creation.

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 what is returned, then the use cases, then the read-only and error caveats. The long parenthetical field list is dense but each item is a concrete datum the agent may need to reference; the only mild waste is repeating 'Read-only' where annotations already say so.

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

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

No output schema exists, so the description carries the burden of describing return contents, and it does so field-by-field, plus documents the onboarding error. An agent knows what it will get, why to call it, and how it can fail.

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

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

The tool takes zero parameters, which is the baseline-4 case: there is nothing for the description to disambiguate, and the empty input schema is unambiguous.

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 (Returns) and resource (the account's sender settings), then enumerates the domains covered: company/address, tax IDs, bank details, invoice defaults, reminders, DATEV numbers. This clearly separates it from update_sender_settings and from invoice-level siblings like get_invoice, which read per-document data.

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 three concrete reasons to call it: learn the date format accepted by invoiceDate/dueDate in create_invoice and create_invoice_from_previous, inspect defaults applied to omitted fields, and show the user what appears on invoices. Ties directly to named siblings. Missing only an explicit negative case, e.g. 'use update_sender_settings to change these values.'

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the description's 'Read-only' sentence is largely redundant. It does add real value beyond the annotations with ordering ('newest first'), per-entry fields ('amount in cents and the balance afterwards') and a scope exclusion (Billstride credits only, not payments), but leaves page size interplay and pagination metadata unstated.

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 usage hint and the scope caveat. The 'Read-only' sentence is the only one that does not earn its place, since annotations already cover 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?

With no output schema, the description carries the burden of describing returns and it does so reasonably: entry types, amount in cents, and post-transaction balance. It omits whether a total count or has-more indicator is returned for pagination, a minor gap for a paged read tool.

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

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

Schema coverage is 100% and both parameters (page, limit) carry their own descriptions with defaults and maxima, so the schema does the work. The description's 'at most 100 entries per page' merely restates the limit maximum and says nothing about paging through results.

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

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

Names a specific verb and resource ('Lists the account's credit ledger') and enumerates the entry types it returns (invoice charges, top-ups, voucher redemptions, refunds). It also draws a hard scope boundary against customer payments on invoices, though it never names the closest sibling get_balance, leaving that differentiation implicit.

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 concrete use cases ('explain a balance or find what an invoice cost') that tell an agent when this tool is the right pick. It stops short of naming an alternative tool or stating exclusions, so the agent must infer that get_balance is the summary counterpart.

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

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

Beyond the readOnly/idempotent annotations, it discloses pagination defaults (50/page, max 100, page-numbered), warns that counts/totals are not revenue figures and include drafts and credit notes, and explains the exact-company-name linkage rule. These are non-obvious semantics that materially affect interpretation of results.

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 purpose and fields, then caveats and alternatives in a logical order. Slightly dense at six sentences, and 'Read-only' duplicates an annotation, but every sentence carries actionable content.

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

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

With no output schema, the description supplies the returned fields, aggregation caveats, pagination limits, and the linkage semantics an agent needs to interpret results correctly, plus sibling disambiguation. Nothing material is missing.

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

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

Schema coverage is 100% and already documents page, limit, and case-insensitive search, so much of the description repeats it. What it adds is framing: search keeps company names containing the text, and paging is by page number with the stated page-size bounds — modest but genuine meaning on top of 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?

Opens with a specific verb and resource plus the exact returned fields, sort order, and per-customer invoice counts. It is clearly distinct from list_recipients and get_customer, which are 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?

States the concrete use cases (finding a customer id, seeing all clients including never-invoiced ones) and contrasts with two alternatives: list_recipients reads from finalized invoices and has nothing for uninvoiced customers; get_customer gives the full address. Routing is unambiguous.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description still adds genuinely new behavior: a hard result cap, page-number or cursor paging, omission of line items, and a caveat about ISO date parsing regardless of sender format. Only rate limits or ordering guarantees for paging are 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?

Three front-loaded sentences: what it returns, when to use it, then the operational constraints. The parenthetical field list is long but each item maps to actionable filtering/sorting information; only the paging 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?

With no output schema, the description correctly compensates by enumerating return fields, stating the result cap and paging mechanism, and clarifying what is not returned. An agent can call and interpret this tool without further context.

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 goes beyond it by explaining that dateFrom/dateTo must be ISO YYYY-MM-DD even when the sender's own format differs, which resolves a real ambiguity the schema doesn't address.

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?

Specific verb (Lists) plus resource (invoice summaries) and an explicit enumeration of the returned fields. It distinguishes itself from get_invoice by noting that identifiers and summaries come from here while line items come from the 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?

Gives concrete when-to-use cases (finding an invoice id, the most recent invoice or client, reviewing drafts/unpaid/overdue) and explicitly routes to get_invoice when line items are needed. The exclusion is stated, not implied.

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

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

Goes well beyond the readOnlyHint annotation by disclosing sort order (company name), the absence of dates and therefore the inability to answer recency questions, the exclusion of draft-only recipients, and the fact that the list is not paginated. These are exactly the traits an agent needs to avoid misusing the result.

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 purpose and returned fields, then caveats. Every sentence carries non-redundant information: what it returns, when to use it, sort order, exclusions, and no-pagination 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?

With no output schema and no parameters, the description must carry both intent and result shape, and it does: it names the returned fields, the deduplication rule (latest finalized invoice), and the limits (no dates, no drafts, no pagination). Nothing an agent needs to call or interpret it is missing.

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

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

The tool takes zero parameters, so the baseline is 4. The description usefully describes the shape of each returned recipient (address, VAT ID, email, invoice number from the latest finalized invoice), which compensates for there being no output schema.

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

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

States a specific verb and resource ('Lists the customers the account has invoiced') and immediately qualifies it with the exact fields returned, which separates it from a generic customer list. It does not explicitly name list_customers or get_customer as the alternative, so the sibling distinction must be inferred rather than read.

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?

'Use it to look up a customer's details before creating an invoice' gives a concrete trigger tied to a sibling action (create_invoice). What is missing is an explicit contrast with list_customers/get_customer for the same lookup, so the agent still has to reason about which list to 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?

Goes well beyond the annotations by disclosing irreversibility, the one-per-account limit, the error-on-repeat behavior, and a full set of failure conditions (unknown, inactive, expired, used-up, or currency-mismatched codes). The repeat-call-is-an-error wording sits slightly awkwardly with idempotentHint=true, but it is a nuance of error handling rather than a contradiction of the no-additional-effect guarantee.

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 its effect, then usage, then constraints and failure modes. Four sentences, each carrying distinct information, with no restatement of the name or 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?

For a one-parameter mutation with no output schema, the description covers effect, irreversibility, and error cases. The only real omission is what a successful response contains (returned credit amount or new balance), which the agent would otherwise have to discover at runtime.

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 single parameter is already documented as "Voucher code to redeem", so the schema does the work. The description adds implicit validity constraints (the code must exist, be active, unexpired, unused, and currency-compatible) but nothing about the code's format or length.

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 (redeems) and resource (voucher code) plus the concrete effect: the amount is added to the account's credit balance. This is unmistakably distinct from every sibling tool, which all deal with customers, invoices, or reporting rather than credit balances.

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

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

Explicitly says when to call ("when the user gives a voucher code to apply") and effectively when not to repeat it ("Each voucher works once per account, so repeating the call adds nothing and returns an error"). No alternative sibling could be confused with it, so absence of a named alternative is not a 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?

The description adds substantial context beyond the annotations: the email goes to a third party, cannot be recalled, every call sends another email, and rate limits of 50 per day, 5 per invoice, and 5 per recipient apply. It also discloses side effects such as recording the send in email history and saving the address as the invoice recipient if none exists.

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 dense but well structured: purpose first, then delivery semantics, preconditions, limits, and side effects. Every sentence contributes operational information.

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

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

Given the mutation and external-send nature of the tool, the description covers preconditions, irreversible side effects, rate limits, history recording, and recipient persistence. It leaves no critical gap for an agent deciding whether and how to call 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 schema already defines all four parameters. The description still adds useful meaning by clarifying that "to" is where the email is sent and that the address may be persisted as the invoice's recipient, which goes beyond the raw schema.

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

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

The description states a specific verb and resource: emails a finalized invoice as a PDF attachment to the address in "to." This clearly distinguishes it from siblings such as get_invoice_pdf, send_reminder, and create_invoice.

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

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

It explicitly says to use it to deliver an invoice to a customer, and clarifies that the invoice must already be finalized and that the tool does not finalize drafts or spend credits. These are clear when-to-use and when-not-to-use constraints.

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 adds substantial behavioral context beyond the annotations: the email goes to a third party and cannot be recalled, the wording cannot be changed, the reminder is recorded in email history, and account or invoice reminder switches do not block this tool. These details are consistent with the destructive and open-world annotations.

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

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

The description is long but front-loaded and dense with decision-relevant information. Every sentence earns its place by covering purpose, constraints, tier behavior, settings caveats, and history recording.

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

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

Given the destructive external-email action, absence of an output schema, and the two-parameter schema, the description is complete enough for correct invocation. It covers failure modes, tier semantics, side effects, and where to verify prior reminders.

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?

Although schema coverage is already 100%, the description meaningfully expands parameter semantics. It explains that omitting tier auto-selects the currently due automatic tier and fails if none is due, while providing a tier sends that tier regardless of day thresholds and fails if already sent.

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: it emails a payment reminder with the invoice PDF attached to the invoice's stored recipient email. It clearly distinguishes the action from sibling tools like send_invoice and get_email_history by focusing on chasing an unpaid invoice.

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

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

It states when to use the tool (to chase an unpaid invoice) and provides explicit when-not conditions, including unpaid status, finalization, credit note status, due date, recipient email, and duplicate reminder refusal. It also points to get_email_history for checking reminders already sent.

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 readOnlyHint, idempotentHint, and non-destructive behavior, and the description adds important caveats beyond them: it does not reserve the number, does not check whether the number is unused, and returns no suggestion when no numbered invoice exists. The return value's exact shape is not described, keeping this from a 5.

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

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

Front-loads the core behavior, then gives a concise usage cue and a compact caveat. Every sentence carries distinct information with no repetition.

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

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

Given a single optional parameter, full schema coverage, strong annotations, and no output schema, the description covers the mechanics, usage context, and key limitations. It could be slightly more complete by indicating the return type (e.g., a number string or null), but it is otherwise sufficient to call the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents the single optional parameter and its omission behavior. The description adds meaning by specifying 'exact company name' for the recipient scope, which goes slightly beyond the schema wording.

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 ('suggests the next invoice number') and explains the exact mechanism: incrementing the trailing number of the latest numbered invoice. It also distinguishes the scoped and unscoped modes, so an agent can separate it from sibling tools like create_invoice or duplicate_invoice.

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

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

Explicitly says to use it 'before creating or finalizing an invoice that needs a number,' which gives a clear trigger condition. It does not name a specific sibling alternative or exclusion, but the usage context is unambiguous.

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

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

Annotations only say destructive/idempotent/non-read-only; the description goes far beyond them by spelling out overwrite semantics ("the old value is not kept"), the empty-string-clears-a-field rule with its companyName exception, atomic rejection on duplicate company name, no VAT ID format validation, and the surprising web-app side effect that saving an invoice rewrites the record's address/VAT/email. It also explicitly disclaims a side effect ("It does not email anyone"), which prevents a false assumption.

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 scope sentence is front-loaded and each sentence contributes a distinct, non-obvious fact. It runs long as a single unbroken prose block, though, and the web-app overwrite quirk is buried mid-paragraph rather than set apart, which slightly hurts 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 a 10-parameter destructive mutation with no output schema, the description covers the things an agent most needs: partial-update semantics, clear-field syntax, failure mode and atomicity, immutability of one field, and side effects on invoices. Nothing material for correct invocation is 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?

Schema coverage is 100%, so baseline is 3, but the description adds semantics the schema does not carry: empty string as a clear-field sentinel (with the companyName exception), company-name uniqueness enforced at save time, VAT ID stored verbatim without validation, and debtor number being immutable. That is genuine added meaning rather than restatement.

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?

"Changes one customer record, chosen by id" is a specific verb + resource + cardinality, and it is immediately distinguishable from create_customer, delete_customer, and get_customer. The follow-on sentence enumerates the exact fields in scope (company name, address, VAT ID, email), so an agent knows what this tool is for 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?

"Use it to correct a company name, address, VAT ID or email" gives an explicit use case, and the constraints (debtor number cannot be changed, invoices are not altered) implicitly bound when not to reach for it. There is no explicit naming of an alternative sibling, but create_customer/delete_customer are self-evidently different, so the routing need is largely satisfied.

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

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

Annotations declare destructiveHint=true and idempotentHint=false; the description substantiates both with concrete consequences: on a draft everything omitted is reset to empty or sender defaults, and on a finalized invoice edits change a document the recipient may already hold with previous values not kept. It also discloses the credit spend (free invoice first, then per-invoice deduction, non-refundable), the finalized-to-draft irreversibility, and the customer-record side effect, none of which annotations convey.

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

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

The core operation is front-loaded, but the body is an undifferentiated wall of text with no paragraphing or grouping, and the lineItems/discounts rules are stated at least twice (the locked-field paragraph and the later "matched to the stored rows by position" paragraph). The date-parsing tangent about 03/04/2026 and 31.02.2026 is genuinely useful but runs long, and the draft/vs-finalized reset rules are repeated again in the schema properties.

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 22-parameter mutation with no output schema, an agent has what it needs: state-dependent semantics, locked versus mutable fields, credit cost and failure mode, side effects, and the fact that no email is sent. Nothing material about calling it correctly is 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?

With 22 params at 50% schema coverage, the description is doing real work: it explains that on finalized invoices number, date, currency, shipping, discounts, line count and each line's quantity/unit/price/VAT/discount are locked while titles and descriptions can change, that position matching applies, that empty string clears only the listed optional text fields, and that unitPrice is decimal while VAT is basis points. That is semantic guidance the schema's partial coverage does not supply.

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 opening sentence states a specific verb and resource ("Replaces an existing invoice") and immediately scopes the behavior by document state. The follow-up enumerates the three legitimate intents (edit draft, finalize draft, correct finalized invoice), which lets an agent distinguish this from create_invoice, duplicate_invoice and update_customer without opening any schema.

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

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

It gives explicit usage contexts and names get_invoice as the companion read call to fetch current values before writing. What is missing is an explicit when-not clause — nothing says to use create_invoice for new documents or duplicate_invoice to fork one — so routing to siblings still requires 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?

Goes well beyond the annotations (readOnly=false, destructive=true, idempotent=true) by disclosing overwrite semantics with no retained old value, warning that this matters for bank details printed on invoices, and clarifying that only new invoices pick up the change while existing invoices retain their original sender details. The onboarding prerequisite is also stated, which no structured field carries.

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 field inventory, then the overwrite warning, then the invoice-impact consequence and the onboarding caveat. It is dense with long parenthetical enumerations, but each clause (especially the bank-details warning and the new-vs-existing invoice rule) 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 29-parameter, zero-required mutation with no output schema, the description covers side effects, scope of effect on existing invoices, and the blocking precondition. It does not say what the call returns on success or how validation failures surface, which is the only material gap.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds value by grouping the 29 parameters into meaningful families (address, tax/VAT, bank, invoice defaults, DATEV) and by stating that only supplied fields are changed, which clarifies that every field is optional. It still gives no per-parameter format or unit guidance beyond what the schema documents.

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 ('Changes the account's sender settings') and enumerates the field families covered: company/address, tax and VAT IDs, bank details, invoice defaults, DATEV numbers. It explicitly contrasts with the sibling read tool, so an agent can separate it from get_sender_settings 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?

Names the alternative explicitly ('get_sender_settings returns the current values') and gives a hard precondition: it cannot create settings for an account that has not finished onboarding in the web app. The when-to-use is stated ('use it to change any of these'), and the read counterpart is routed away.

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