Netto

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

Annotations already cover the safety profile (readOnlyHint, openWorldHint=false), and the description adds real behavioral context: an implicit default period and an instruction to invoke immediately rather than asking a clarifying question. It also implicitly describes the returned content (attached vs missing). It does not state pagination or any rate/limit behavior, so it stops short of 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?

The purpose and default-period directive are front-loaded, and the example phrasings are short and each earns its place by covering a distinct user phrasing. No filler sentences.

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?

One optional enum parameter, no output schema, and no nested structures — the description specifies purpose, invocation default, and the shape of the answer (attached vs missing). Nothing an agent needs to call this correctly 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?

Schema coverage is 100% and the single param is a self-explanatory enum, so the baseline is 3. The description adds value beyond the schema by endorsing current_quarter as the operative default and telling the agent not to solicit the period from the user, which is meaning the schema does not 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?

States a specific verb+resource: reports which expenses have receipts attached and which are missing, scoped to a period. It clearly separates itself from the adjacent expense-query siblings by focusing on receipt completeness, though it never names those siblings 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?

Explicitly routes the agent: 'Use for ANY question about receipts' with three concrete example phrasings that map to likely user intents. It also gives a decisive default ('call it straight away with the current quarter unless the user named another period — do not ask which period first'), removing ambiguity about both when to use it and how to open the 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 (not read-only, not destructive, not idempotent), so the description earns credit for adding the defaults behavior instead: country NL, currency EUR, payment terms from business default — and the last two are leaked defaults not exposed as parameters at all. It does not warn that repeated calls can create duplicate clients despite idempotentHint=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?

Three short sentences, front-loaded with the action, then the hard requirements, then the defaults. Nothing is repeated and every clause carries information an agent needs.

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 non-destructive create with no output schema, the description covers action, required fields, and defaulted behavior. The remaining gap is the return value — whether the created client's identifier comes back, which matters for chaining into invoice 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 already 86%, so the baseline is 3; the description goes beyond it by explaining why name and address are required (Dutch invoice law) and by disclosing currency and payment-terms defaults that appear nowhere in the schema. Optional fields like vatNumber and postalCode rely entirely on the schema, which is acceptable at this coverage.

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

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

States a specific verb and resource ('Create a new client contact'), which cleanly separates it from the query-side siblings (lookup_contact, query_clients) without naming them explicitly. The domain rationale ('legally required on a Dutch invoice') sharpens what a client record is here.

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 / when-not guidance, no mention of checking for duplicates via lookup_contact, and no stated prerequisites or follow-on steps. Usage is only implied by the invoicing rationale, so an agent must infer that this belongs before create_invoice_draft/create_quote_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?

Annotations already declare non-destructive, non-idempotent, closed-world writes; the description adds real context beyond them: no external delivery occurs, the response contains an openUrl for user review, and a confirmation step should follow. It doesn't cover failure modes or what happens if a duplicate draft is created, which keeps it below 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?

Four short sentences, no filler, and the critical facts — what it does, the prerequisite, the no-send guarantee, and the review URL — are front-loaded. Every sentence carries distinct 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?

With no output schema, the description usefully discloses that the result includes an openUrl, and it defines the full workflow from contact lookup to send confirmation. Minor gaps remain around validation errors or duplicate-draft behavior, but nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so contactId, lines, dueDate, and notes are all documented in the schema itself. The description only restates the contactId provenance (lookup_contact), which the schema already says, and adds no line-item or dueDate semantics. 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 ("Create a draft invoice") and immediately clarifies scope with "Nothing is sent," which cleanly separates it from send_invoice and, by resource noun, from create_quote_draft. An agent can identify the operation 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 an explicit prerequisite sequence ("Call lookup_contact first to get the contactId") and a follow-up action ("afterwards ask whether to send it"). It stops short of naming an explicit alternative such as create_quote_draft for quotes, but the draft-versus-send distinction is made 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 non-destructive, non-open-world, non-idempotent; the description adds valuable context beyond them: nothing is transmitted and the result carries an openUrl for the draft. It omits whether repeated calls create duplicate drafts, which matters for a non-idempotent 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?

Three short sentences, front-loaded, with the prerequisite and side-effect called out immediately. The opening sentence largely echoes the title, but nothing else 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 mutation tool with annotations present and no output schema, the description covers side effects, prerequisite flow, and the return's key field (openUrl). Only the duplicate-draft behavior is left unaddressed.

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 75% schema coverage, the nested line fields (btwRate defaults, unitPrice in EUR) and validUntil default are already documented in the schema. The description adds no parameter meaning of its own, 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?

"Create a draft quote" states a specific verb and resource, and "Nothing is sent" implicitly distinguishes it from send_quote in the sibling list. It never names the alternative explicitly, so it falls short of a clean sibling differentiation.

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 prerequisite ordering ("call lookup_contact first") and clarifies the non-sending scope, which is real when-to-use guidance. It stops short of naming send_quote as the tool to use when the quote should actually go out.

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 disclose that this is a non-read-only, non-destructive, non-idempotent, closed-world operation. The description adds the contact lookup prerequisite but does not explain duplicate-logging risk, reversibility, or what happens after logging, so it adds only moderate behavioral context beyond annotations.

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

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

Two tight sentences with no wasted wording. The primary action is front-loaded, and the prerequisite follows immediately.

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

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

The tool is a mutation with annotations covering safety and idempotency, and the schema fully documents inputs. The description covers purpose and the key contactId prerequisite; only minor gaps remain around duplicate handling and post-call behavior, with no output schema to explain return values.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema. The description adds a useful relationship between a mentioned client and contactId, but does not explain the other 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 names a specific verb and resource: 'Log billable hours for a client or project.' It is clear what the tool does, though it does not explicitly distinguish itself from any sibling, likely because no sibling is a close 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?

It gives a concrete prerequisite: call lookup_contact first if a client is mentioned to obtain the contactId. That is useful routing guidance, but it does not discuss when not to use the tool or compare it against alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds one genuinely useful behavioral trait — matching is fuzzy, not exact — and the mandatory pre-call positioning, but says nothing about multiple matches, ranking of near-matches, or what the agent should do with an ambiguous 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?

Two sentences, zero filler, with the core purpose first and the ordering rule second. 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?

Adequate for a one-parameter read-only lookup whose annotations carry the safety profile and which has no output schema to explain. The remaining gap is disambiguation behaviour — what a partial or multi-match returns and whether the resulting contact id is what downstream draft tools need — which would materially help an agent chain the 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?

Schema coverage is 100% and there is only one parameter, so baseline is 3; the description earns a bump because "fuzzy-search" tells the agent to pass a plain name rather than an exact string or wildcard pattern, which affects how the value should be formed.

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 matching mode ("fuzzy-search") plus the resource ("existing client/contact") and the key field (name). An agent can immediately distinguish it from create_contact or query_clients.

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 ordering rule and names the three sibling tools it must precede (create_invoice_draft, create_quote_draft, log_time) with the trigger condition "when a client is mentioned." It does not say what to do when no match is found (create_contact?) or when query_clients would be preferable, so the when-not half is absent.

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, it discloses that nothing executes on this call, that execution is gated on a user opening the link and pressing Confirm in Netto, and that the link expires in 30 minutes. These are exactly the operational facts an agent cannot infer from destructiveHint/readOnlyHint 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?

Short, front-loaded, and every sentence carries operational weight (deferred execution, expiry, prohibition on claiming success). Slight redundancy between 'Nothing happens yet' and 'the action only runs after they open it' keeps it from a 5.

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 steps in to describe the return value (a confirmUrl) and its lifetime, plus the interaction contract. That covers the critical unknowns for a destructive, open-world, non-idempotent 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 invoiceId, customerName, and paidDate are already documented in the schema. The description adds no extra meaning about what customerName is used for or how paidDate feeds the confirmation, 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 ('Prepare marking one invoice as fully paid') and immediately clarifies the two-phase nature of the operation. An agent can tell this is not send_invoice or query_invoices because the deliverable is a confirmation link, not an immediate mutation.

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

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

Explicitly instructs the agent to hand the confirmUrl to the user and to never claim the action was done — strong when-to/how-to guidance with a hard prohibition. It stops short of naming alternatives (e.g., when to use send_reminder instead for unpaid invoices), so 4 rather than 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?

Beyond readOnlyHint/openWorldHint, it discloses the default-selection algorithm (ended-and-unfiled, else running quarter), the full state taxonomy with definitions, and the computation formulas for totalVatOwed and netPayableEur including sign meaning. This is substantial behavioral detail an agent could not infer from 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 core purpose is front-loaded in the first clause, followed by default behavior, state definitions, and formulas. It is dense but nearly every clause carries needed information; the state enumeration and formulas could be slightly tightened 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?

With no output schema, the description compensates by naming the returned fields (state, deadline, figures, otherQuarters, totalVatOwed, netPayableEur) and their semantics. Combined with 100% schema coverage on the two optional params, an agent has everything needed 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%, so the baseline is 3, but the description adds real semantic value: it explains what happens when year/quarter are omitted (the fallback selection logic), which the schema only tersely states as 'defaults to current quarter.' That is meaningfully beyond the schema text.

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

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

The description opens with a specific resource and its payload: 'A BTW (VAT) return: its state, filing deadline and figures.' An agent knows exactly what this returns. It does not explicitly contrast with siblings like query_financials or query_expense_breakdown, 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?

It clearly explains the no-argument case ('returns the return that needs the user first, as the VAT page does'), which tells an agent when to call it bare vs. with year/quarter. There are no explicit exclusions or named alternative tools, so it is clear context without full when-not guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description usefully says the response includes a count and a revenue ranking, but omits how many clients constitute 'top', how ties are handled, and whether the two results are combined or separate — meaningful gaps beyond what annotations supply.

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; the resource and the two outputs are stated up front and 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 read-only tool with no output schema, the description adequately conveys both the inputs (period) and the shape of the result (count plus top clients by revenue). The remaining detail an agent might want — the size of the 'top' list and ordering semantics — is absent but 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?

The schema has full coverage of the single parameter, including an enum of accepted period values and its own description, so the description need not elaborate. The description only says 'for a period', adding nothing about enum members or semantics — baseline 3 is correct.

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

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

States a specific verb and resource: retrieve unique client count plus top clients ranked by revenue, scoped to a period. It is distinguishable from sibling query_* tools by naming client analytics rather than invoices, expenses or financials, though it never explicitly contrasts with 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?

Usage is only implied by the phrase 'for a period' — an agent can infer this is a period-scoped client report, but there is no statement of when to prefer it over query_financials or lookup_contact, nor any prerequisite or exclusion.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that results are grouped by category and scoped to a period, but says nothing about whether the response is totals only or per-category rows, nor about currency or zero-expense categories. Useful but thin beyond annotations.

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

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

One short, front-loaded sentence with zero filler. Brevity is appropriate, though it leaves the reader wanting a little more on what a 'breakdown' contains.

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 is the only place to hint at return shape, and it omits whether results are an aggregated total per category, a list of line items, or a chart-ready series. For an aggregation tool whose output is the whole point, that is a meaningful gap.

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

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

Schema description coverage is 100% and the single parameter is a fully enumerated 'period' field, so the schema does the work. The phrase 'for a period' merely restates the parameter and adds no interpretation such as calendar vs fiscal quarter boundaries.

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 ('Get expenses broken down by category') plus scope ('for a period'), which clearly distinguishes it from detail-oriented siblings like query_expense_detail. It does not name any sibling explicitly, so differentiation must be inferred from the word 'breakdown'.

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 statement of when to use this versus query_expense_detail, query_financials, or query_btw, all of which plausibly overlap. The agent must guess that 'breakdown' means aggregated-by-category rather than itemized.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safe read-only profile is covered. The description adds the drill-down workflow context but says nothing about return shape, result volume, or what happens when a category has no activity — modest added value beyond the annotations.

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

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

Three short sentences, front-loaded with purpose then usage then the code-vs-name flexibility. Nothing is wasted or buried.

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 lookup with full schema coverage and annotations, the description is sufficient to invoke correctly. Only minor gaps remain around what the expense records contain, which is not strictly required for invocation.

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

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

Schema coverage is 100% and the schema descriptions already state that categoryCode accepts either an account code or an account name. The description repeats that fact rather than adding anything new, so baseline 3 is appropriate.

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

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

States a specific verb and resource (get individual expenses) scoped to one account/category and a period. It is clearly distinguishable from the sibling query_expense_breakdown, which is named explicitly as the aggregate-level 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?

Explicitly says to use this after query_expense_breakdown when the user wants to drill into a specific category, giving both the precondition and the alternative. This is exactly the routing guidance an agent needs.

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

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

Annotations already declare this is a read-only, non-open-world query, so the safety profile is covered. The description adds meaningful behavioral context by clarifying that revenueEur/expensesEur/profitEur are net of BTW/ex-VAT and match the dashboard, while also distinguishing gross invoiced/paid 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 core purpose and uses two dense sentences without wasted wording. The field-level clarification is directly relevant to correct interpretation of the returned financial figures.

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 appropriately carries the burden of explaining the return values, including net vs gross fields and invoiceCount. It is nearly complete for a single-parameter summary query, though it does not describe output shape or edge cases.

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

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

Schema coverage is 100%, so the single period parameter and its enum values are already documented in the schema. The description mentions 'for a period' but does not add syntax, default, or enum-specific 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 clearly states the resource and scope: revenue, expenses, and profit for a period. It is specific about the returned metrics, but it does not explicitly differentiate itself from siblings such as query_expense_breakdown, query_btw, or query_invoices.

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

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

The description implies this is the dashboard-matching summary tool and instructs the agent to use its net figures as revenue/expenses/profit. However, it does not explicitly say when to choose this over query_expense_breakdown, query_btw, or query_invoices, so usage remains inferred rather than directed.

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

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

Annotations already declare readOnlyHint and openWorldHint=false, and the description adds real behavior: results are newest-first, open drafts are included, credit notes appear alongside invoices, and voided/written_off statuses exist. It omits result limits and whether credit notes affect totals.

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 scope and ordering, then the returned-field list, then usage. The status enumeration is long but each item earns its place by telling the agent what it can filter/expect.

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

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

With no output schema, the description compensates well by describing the returned fields. Remaining gaps are minor: no result volume/pagination guidance and no note on whether open drafts are unfiltered by period.

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

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

Schema coverage is 100% with a self-describing enum and a documented default, so the schema already carries the parameter meaning. The description only says "in a period" and adds no semantics beyond the enum itself.

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 (query) and resource (invoices) scoped to a period, and enumerates the returned fields including status, type and credit-note linkage. It implicitly separates itself from query_open_invoices by noting it also returns paid/cancelled invoices, but never names the 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?

"Use for questions about specific invoices, paid or cancelled ones, or credit notes" gives clear selection context, which contrasts with the open-invoices-only sibling. No explicit exclusions or named alternatives, so it stops short of the top band.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds value beyond that by disclosing the response shape (count/total, aging breakdown, per-entry invoiceId). It does not mention ordering, limits, or freshness, which are relevant for an aging report.

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 what is returned and followed by the actionable link to sibling tools. Every clause earns its place with no redundancy.

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

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

With no parameters and no output schema, the description carries the burden of describing returns, and it does so at a high level (count, total, aging breakdown, invoiceId). It leaves the exact aging bucket boundaries and whether totals are per-currency unstated, a minor gap.

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

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

Zero parameters, so there are no semantics to explain and the baseline of 4 applies. The description correctly spends none of its budget on parameter 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 ('Get count/total of open and overdue invoices plus aging breakdown'), scoping it narrower than the generic query_invoices sibling. It never names query_invoices explicitly, so the differentiation is inferred from the 'open and overdue' qualifier 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?

Gives clear downstream guidance: the returned invoiceId feeds send_reminder or mark_invoice_paid. It stops short of stating when to prefer this over query_invoices or how often aging data refreshes, so no explicit exclusions are offered.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds useful behavioral detail about the return shape: best matching articles with a link and the most relevant part, which helps the agent understand what to expect beyond structured annotations.

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

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

Two sentences, front-loaded with the action and resource, followed by the return behavior. There is no filler or repetition, and every sentence contributes useful 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 simple two-parameter read-only search tool with full schema coverage and no output schema, the description covers purpose and return behavior adequately. It does not mention result limits or pagination, but those are minor omissions for this tool's complexity.

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

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

Schema description coverage is 100%, so both the query and language parameters are already documented in the schema. The description adds no parameter-specific meaning beyond what the schema provides, which is appropriate for a baseline score of 3.

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 (Search) and resource (Netto's help center), and the parenthetical clarifies the content scope (how to use the app, step by step). The sibling tools are all financial operations, so this is clearly distinguishable without ambiguity.

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

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

The description implies usage by scoping the content to how-to app questions, but it does not explicitly say when to use this versus alternatives or when not to use it. An agent can infer the context, but no direct routing guidance is provided.

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: discloses that nothing happens on call, that the response carries a confirmUrl, the 30-minute link lifetime, and the required human confirmation step. This is exactly the context destructiveHint/openWorldHint=true implies but cannot state, and it does not contradict them.

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

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

Five short sentences, front-loaded with what the tool does and what does *not* happen. Each sentence carries a distinct operational fact 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?

Despite having no output schema, the description explains the salient return field (confirmUrl), its lifetime, and the required user interaction, plus the critical instruction never to report completion. Nothing an agent needs to invoke and report correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema. The description only alludes to 'draft invoice' and 'client' without adding format or selection guidance, 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?

Names a specific two-phase action and its exact resource: preparing an email of a *draft invoice* to the client. The draft-only precondition and the confirm-link mechanism distinguish it from send_quote and send_reminder without needing the 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?

Explicitly tells the agent how to use the result (give the confirmUrl to the user, it only runs after they press Confirm, valid 30 minutes, never claim it was done). It doesn't name alternative siblings or when not to call it, but the operative guidance is unusually 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?

Adds substantial behavior beyond the annotations: the call is a no-op that returns a confirmUrl, execution is deferred to a human confirmation step, and the link expires after 30 minutes. It also explicitly warns the agent not to report completion, which directly complements destructiveHint=true without contradicting it.

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

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

Four short sentences, front-loaded with the core constraint ('Nothing happens yet'), followed by the required agent action and the expiry. Nothing is redundant.

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

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

There is no output schema, and the description compensates by naming the returned confirmUrl and explaining what the agent must do with it. Combined with annotations covering the destructive/open-world profile, an agent has everything needed to call and handle this tool correctly.

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

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

Schema coverage is 100%, so quoteId and customerName are already fully documented in the schema. The description adds no extra meaning about either parameter, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('emailing a draft quote to the client') and frames it precisely as a preparation step. It does not name any sibling (e.g. send_invoice or create_quote_draft), so differentiation is left to the agent, which keeps it 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?

It gives clear operational guidance after the call (give the user the link, the action only runs on Confirm, never say it was done) but never states when to choose this over send_invoice or create_quote_draft, nor any prerequisite for the quote being a draft. Usage context is implied rather than scoped.

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?

With destructiveHint=true and readOnlyHint=false in the annotations, the description adds the crucial nuance that the tool only prepares the action: 'Nothing happens yet', a confirmUrl is returned, the human must press Confirm in Netto, and the link expires in 30 minutes. It also gives an output-reporting rule ('Never say it was done'), which is exactly the behavioral context annotations cannot carry.

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

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

Front-loaded with the action and scope, then the prerequisite, then the confirmation contract and the expiry. Five short sentences, each carrying distinct operational information, with 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?

There is no output schema, and the description compensates by describing the return value (a confirmUrl) and its lifecycle. Combined with the parameter constraints and the two-step human-in-the-loop flow, an agent has everything needed to call it and report 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 both parameters are already documented. The description adds the constraint that invoiceId must reference an open or overdue invoice, but says nothing about customerName or how it is used in the confirmation reply. Baseline 3 is appropriate given the schema does the heavy lifting.

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

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

States a specific verb and resource ('Prepare a payment reminder email for one open or overdue invoice') with the scope constraint (single invoice, open/overdue) and escalation behavior. It also names the sibling tool that supplies the input (query_open_invoices), so it is distinguishable from send_invoice and send_quote 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?

Explicitly says where to get invoiceId ('Use invoiceId from query_open_invoices') and limits the tool to open or overdue invoices. It does not state when to prefer an alternative (e.g. send_invoice for a new invoice, or check_receipts before chasing), so the exclusion side is implied rather than spelled out.

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 this as a non-read-only, non-destructive, non-idempotent update. The description adds the critical behavioral detail that the line list is fully replaced and that all existing lines must be passed, which goes beyond the annotations and prevents accidental data loss.

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 three tight sentences with the core action and replacement warning front-loaded. Every sentence contributes useful guidance, and there is no redundant 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?

For a five-parameter mutation tool with no output schema, the description covers the main invocation requirements: draft-only scope, required ID provenance, and full line replacement. It does not explain what the tool returns or mention the optional notes/dueDate parameters, but the schema covers those fields adequately.

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 documents most parameters. The description adds operational meaning by stressing that the lines parameter must contain the complete new line list, including unchanged lines, which is more actionable than the schema's 'Complete new line list' phrasing 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?

The description states a specific verb and resource: update an existing draft invoice by adding, removing, or changing lines. It distinguishes this from create_invoice_draft by tying it to a draft that was just created and by sourcing the IDs from the create response.

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 says to use this when the user wants to modify a draft that was just created, and it explains where to get invoiceId and contactId. It does not explicitly state when not to use it or name an alternative for non-draft invoices, but the context is clear.

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