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

Annotations already declare readOnlyHint=true and openWorldHint=true, and an output schema exists, so the bar is lower. The description still adds genuinely useful behavioral context the annotations cannot: the ledger sign convention (debit positive, credit negative) and that the figures are derived from the SIE export, which tells the agent how to interpret and compare the numbers.

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

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

Three short sentences, zero filler: purpose first, sibling disambiguation second, interpretation cue third. Nothing is repeated from the structured fields and nothing could be cut without losing routing or interpretation value.

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

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

With read-only annotations, a full output schema, and 100% parameter coverage, the description only needs to carry purpose, routing, and interpretation — which it does. It is slightly thin on the fiscal-year/date-default interaction, but that is already documented in the schema.

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

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

Schema description coverage is 100%, including the date defaulting rule, company default, account filtering, and the not-found behavior for unknown fiscalYearId. The description adds nothing about parameters beyond what the schema already says, so the baseline of 3 applies.

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

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

States a specific verb (compute) and specific outputs (opening balance, movement, balance per account at a date) drawing on the SIE export. The follow-on sentence explicitly contrasts it with bokio_account_ledger, so an agent can pick between them without opening either schema.

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

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

'Use it for what is on an account at a date; bokio_account_ledger shows the individual lines' gives a clear selection rule against the nearest sibling. It stops short of stating exclusions or prerequisites (e.g., that a fiscal year or company must be resolvable first), so it is clear context rather than a full when/when-not map.

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 readOnlyHint and openWorldHint annotations, the description discloses important behavior: results are ordered by date, series, and number; a running balance is included; annulled verifications are kept but flagged cancelled; and debit/credit sign conventions are specified. These details materially affect interpretation of 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?

The definition is three tight sentences, front-loaded with the core purpose and followed by the sibling distinction and result-sign convention. Every sentence adds useful information with 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?

Given the moderate complexity, complete schema descriptions, existing output schema, and annotations, the description is complete enough for correct invocation. It covers purpose, alternative routing, result ordering, cancellation handling, and sign convention without needing to explain return columns that the output schema already defines.

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 four parameters are already documented in the input schema. The description restates the account and date-range meaning but adds no syntax, defaults, or constraints beyond what the schema provides, making 3 the appropriate 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 (list), resource (postings on one account), and scope (between two dates with a running balance). It also names bokio_list_journal_entries as the sibling that lists whole verifications instead, so an agent can distinguish the tool without opening schemas.

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

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

The description clearly establishes when to use this tool: per-account postings over a date range. It explicitly contrasts with bokio_list_journal_entries, which lists whole verifications, giving the agent a direct alternative-selection rule.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered structurally. The description adds the return shape (numbers with names), which is genuinely useful with no output schema, but says nothing about whether the list is paginated, complete, or static per company. With annotations carrying the safety profile, a 3 is appropriate.

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 compact sentences, front-loaded with the identity of the resource and its payload, followed by usage and the sibling distinction. Zero filler and nothing an agent must read twice.

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 partly compensates by stating what comes back (account numbers with names). For a two-optional-param read tool that is nearly complete; the only gap is that the filtering behavior of query is left unexplained.

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 query and companyId parameters are already documented in the schema, including the BOKIO_COMPANY_ID default. The description adds no meaning beyond that — notably it never mentions that the list can be filtered via the query parameter, which is counterintuitive for a chart of accounts. Baseline 3 is correct when the schema does the work.

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

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

States a specific verb and resource ('List the company's BAS chart of accounts') and immediately specifies the payload ('account numbers with names'). It explicitly contrasts itself with the sibling bokio_get_account ('reads a single account'), so an agent can route without opening either schema.

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

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

Gives a concrete use case — 'Use it to find the account number the ledger and balance tools take' — which names the downstream consumers and why you'd call this first. It names the single-account alternative, but offers no explicit exclusion or condition for filtering the list, so it falls just short of a full 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description need only add context beyond safety. It adds that the result is scoped to the token/companyId pair, but says nothing about authentication requirements or the shape of the response.

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

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

Two short sentences, zero filler, with the purpose stated first and the usage scenario 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?

For a zero-required-parameter read tool with no output schema, this is nearly complete: it says what is returned in broad terms and why to call it. A brief note on what the identity lookup covers (or its failure mode) would make it fully self-sufficient.

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

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

Only one parameter with 100% schema description coverage, including the BOKIO_COMPANY_ID default, so the schema carries the load. The description references companyId only as a scoping concept, not adding format or fallback semantics beyond the schema.

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

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

States a specific verb (Get) and resource (the Bokio company's own details), and enumerates the returned fields (name, organisation number). It is clearly distinguishable from the bookkeeping siblings, though it never explicitly contrasts itself 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?

"Use it to confirm which company the token and companyId point at" gives a concrete triggering situation rather than leaving usage implicit. No exclusion or when-not guidance is given, but there is no similar sibling that would require one.

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

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

Annotations only declare readOnlyHint and openWorldHint, so the description's statement that it returns the written path and byte count is genuine added value — especially since there is no output schema to carry that. It does not restate the schema's no-overwrite rule or mention error behavior, but it adds real context beyond the 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?

Two short sentences, action and destination front-loaded, return values second. No filler or 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?

For a simple file-download tool with a fully documented schema, the description covers purpose, target, and outcome. The only material gap is what happens for a draft/unpublished credit note, which the word "published" hints at but never explains.

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 already documents savePath semantics, the BOKIO_COMPANY_ID default, and the not-found behavior for unknown creditNoteId. The description only echoes savePath's role, adding nothing the schema does not already say, 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 names a specific verb and resource ("Download a published credit note as a PDF file") plus the destination, which clearly separates it from bokio_get_credit_note (metadata fetch) and bokio_list_credit_notes. It lacks only an explicit contrast with sibling download tools like bokio_download_invoice, which differ by resource but are interchangeable in shape.

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

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

The word "published" implies a precondition (drafts presumably cannot be downloaded), but this is stated as an adjective rather than a rule. No guidance is given on when to choose this over bokio_get_credit_note or bokio_download_invoice, and no failure conditions are described.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral context that the annotations cannot convey: the return payload (written path and byte count), which is important given there is no output schema. It does not restate the no-overwrite rule from the schema, but nothing in it contradicts the annotations.

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

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

Two compact sentences with zero waste. The action and destination are front-loaded, and the sibling disambiguation 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?

There is no output schema, and the description compensates by describing the return value (path and byte count). For a simple file-download tool with fully documented parameters and annotations covering safety, this is nearly complete; only error behavior (e.g. unknown invoice id) is left entirely to the schema.

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

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

Schema description coverage is 100%, so all three parameters are already documented, including the savePath no-overwrite constraint and the companyId default. The description only echoes savePath as the destination and adds no syntax or format guidance beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (download), resource (a published invoice), and output format (PDF file) written to a named location. It also explicitly distinguishes itself from bokio_get_invoice, which returns data rather than a file, so an agent can choose between them without opening either schema.

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

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

Names the alternative tool (bokio_get_invoice) and the condition that selects it ('returns the invoice data instead'). The routing decision between retrieving data and downloading a file is fully 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 readOnlyHint=true and openWorldHint=true. The description adds real information the annotations don't cover: the 4,000-character truncation of text mode and the fact that the computed tools parse this same export. It does not discuss export size, encoding, or failure modes beyond the not-found error that the schema already lists.

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 with no filler. The primary mode and its fallback come first, and the routing advice to alternative tools comes second.

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, yet the description fully explains what the agent gets back in both modes: a file at savePath, or the first 4,000 characters as text. Combined with 100% parameter coverage and the named sibling alternatives, nothing needed for correct invocation is missing.

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

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

Schema coverage is 100%, so 3 is the baseline. The description adds meaning the schema does not: omitting savePath changes the tool from file download to inline text, which is the single most consequential parameter behavior here. The remaining per-parameter details (dir precedence, overwrite protection, id source) are already in the schema.

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

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

States a specific verb and resource (download the raw SIE 4 export of one fiscal year) and describes both output modes: file when savePath is present, first 4,000 characters of text when omitted. It also separates itself from the family of computed tools that consume the same export.

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 that balances, ledgers, VAT, and profit and loss should go to the computed tools instead, naming the sibling categories and explaining why (those tools do the arithmetic on this export). The dual-mode condition is also stated outright.

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 readOnlyHint=true and openWorldHint=true already declared, the description adds useful behavior by stating it writes to savePath and returns the written path and byte count. This is valuable because there is no output schema. It does not restate the schema's no-overwrite behavior, but the annotations already establish safety.

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

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

The description is two compact sentences with no redundant text. The main action and destination are front-loaded, followed by return behavior and sibling differentiation.

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

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

For a simple read-only download tool with fully described parameters and annotations covering safety, the description supplies the missing return-value context. It is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so uploadId, savePath, and companyId are already fully documented in the schema. The description mentions savePath implicitly as the destination but does not add syntax or meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: downloading an uploaded file's content to savePath. It also explicitly distinguishes the tool from bokio_get_upload by saying that sibling returns metadata. An agent can tell exactly what this tool does and how it differs from the metadata tool.

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

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

The description clearly indicates this tool is for retrieving file content and names bokio_get_upload as the metadata alternative. It does not explicitly cover when not to use it or mention other download siblings, but the primary usage decision is clear.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered; the description adds real behavioral context beyond that, namely the annulled-verification skip rule and the ledger sign convention (debit positive, credit negative) that determines what 'same amount' means. It does not say whether duplicates come back grouped or flat, or in what order — a small remaining gap.

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

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

Three sentences, front-loaded with the core detection criterion, followed by the exclusion rule/alternative routing, then the sign convention. Every clause carries information the agent needs; nothing is redundant with 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?

A read-only, five-parameter tool with full schema coverage and an output schema — so return shape needn't be described. The description covers detection logic, exclusions, sign convention, and the neighboring alternative, leaving nothing an agent would need 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; the description earns above baseline by defining the matching semantics of windowDays ('within windowDays of each other') and by clarifying the ledger sign convention that governs the amount comparison, neither of which the schema states. It does not add anything for companyId or account beyond the schema's own text.

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

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

States a specific verb (find) and a precisely defined resource (possible double bookings), then spells out the exact matching criterion: same account and amount from different verifications within windowDays. The scope (SIE export) and the sibling it is not (bokio_reconcile_bank) are both named, so an agent can distinguish it 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?

Explicitly routes the agent: 'to check against a bank statement use bokio_reconcile_bank', which names the alternative and the condition that selects it. It also states the exclusion rule ('Annulled verifications are skipped'), so the agent knows what is silently omitted from results.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description need not restate safety. It adds only the routing context; it says nothing about what an account record contains or whether missing numbers error out.

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

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

Two short sentences, zero waste, with the core operation first and the alternative routing second. Nothing could be cut without losing information.

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

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

For a simple two-parameter read with no output schema, this is nearly complete: it names the resource, the key, and the alternatives. The only gap is a hint at what fields the returned account carries or behavior on unknown numbers.

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, including the BAS number example and the companyId default. The phrase 'by number' merely echoes the schema, adding no new semantics.

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

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

States a specific verb (Get), a single resource (one account), and its domain (BAS chart of accounts), keyed by number. This clearly distinguishes it from list/balance/ledger 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?

Explicitly routes the agent to bokio_account_balances and bokio_account_ledger when balance or postings are wanted, which is the main ambiguity for account tools. It does not name an exclusion or prerequisite for this tool itself, but the alternatives are covered.

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

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

Annotations already cover the safety profile (readOnlyHint, openWorldHint), so the bar is lower. The description nonetheless adds real context beyond them: results are scoped to payments created by this integration, which prevents an agent from expecting a complete bank-payment view.

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

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

Two short sentences, zero waste. The core operation is front-loaded and the scope caveat 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?

A simple single-record getter with full schema coverage and annotations carrying the safety profile, so the description needs little more. The scope limitation is the one thing only the description could supply, and it does. Return shape is not described, but no output schema exists, leaving 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?

Schema coverage is 100%, so both parameters (companyId default behavior, bankPaymentId sourcing and not-found error) are already fully documented. The description only echoes 'by id' and adds no syntax or sourcing detail beyond the schema, so 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 ('Get one bank payment by id'), which implicitly contrasts with the sibling list tool bokio_list_bank_payments. It does not name the sibling explicitly, but the singular 'one ... by id' framing makes the distinction unambiguous.

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

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

Adds a genuine usage constraint: the integration only ever returns payments it created, and creation is 'deliberately not exposed' — telling the agent not to hunt for a create tool. It stops short of explicitly routing to bokio_list_bank_payments for id discovery (that hint lives only in the schema).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that the response is 'as Bokio returns it,' signaling a raw vendor-shaped payload rather than a normalized one, but it discloses nothing further about payload structure or failure modes.

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

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

Two short sentences, with the core action first and the sibling routing second. Zero filler.

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

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

For a simple single-record getter with 100% schema coverage and read-only annotations, this is close to complete: it names the identifier source via schema, and 'as Bokio returns it' warns that the payload is vendor-native even though there is no output schema. A brief note on the returned resource shape would close the last 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 both parameters (companyId default behavior, creditNoteId source and not-found error) are already documented in structured form. The description adds only the phrase 'by id' and no syntax or format detail beyond the schema, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('Get one credit note by id') and disambiguates from the two closest siblings by noting the PDF variant belongs to bokio_download_credit_note. An agent can distinguish this from bokio_list_credit_notes and the download tool 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?

Explicitly routes the agent to bokio_download_credit_note when a PDF is wanted, which is the main usage fork. It does not spell out when to prefer this over list_credit_notes, but that distinction is obvious from the singular/plural naming.

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=true and openWorldHint=true, so safety is covered. The phrase "as Bokio returns it" usefully signals an unnormalized upstream payload, but the description says nothing about error behavior or field shape beyond that hint.

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 filler; the core purpose is front-loaded and the sibling pointer trails it. Slightly clipped phrasing ("as Bokio returns it") trades a bit of clarity for brevity.

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

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

With no output schema, the description carries the burden of describing the return value, and "as Bokio returns it" only vaguely gestures at it. For a single-record fetch this leaves the agent guessing which customer fields come back.

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

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

Schema description coverage is 100%, with companyId defaulting documented and customerId's not-found behavior spelled out in the schema. The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("Get one customer by id") and implicitly contrasts with the list sibling by emphasizing singularity. An agent can tell it apart from bokio_list_customers, though the contrast is never stated explicitly.

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

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

The second sentence redirects invoice lookups to bokio_list_invoices, which is genuine routing guidance. However, it never says to use bokio_list_customers first to obtain an id, nor does it exclude any other use case — that pointer only exists in the schema.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only that start and end dates are returned; it says nothing about error behavior, permission requirements, or company scoping beyond what the schema states.

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

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

Two short sentences, front-loaded with the purpose; every clause earns its place by either defining the operation or routing to the alternative.

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 at least names the fields returned (start and end dates) for this simple two-parameter read. Given the tool's low complexity and full annotation coverage, that is close to complete, though a bit more detail on the response would help.

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 already document their semantics, including the not-found error and the BOKIO_COMPANY_ID default. The description adds no parameter-level detail, so this is the baseline case where the schema does the work.

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

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

States a specific verb and resource ('Get one fiscal year by id') and even names the return shape (start and end dates). It explicitly distinguishes itself from the sibling bokio_list_fiscal_years, so an agent can choose between them 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?

The second sentence tells the agent to use bokio_list_fiscal_years when all fiscal years are wanted, which implicitly defines this tool's niche (fetching a single known id). It stops short of stating when-not-to-use (e.g., when the id is unknown, though the schema covers that).

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 the safety profile is covered. The phrase 'as Bokio returns it' adds value beyond annotations by signaling a raw, unnormalized pass-through payload rather than a curated view. It does not discuss error behavior or payload size, so a 4 rather than 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?

Two sentences, no filler, with the core purpose front-loaded and the disambiguation clauses trailing. Every phrase (single-record scope, raw shape, sibling routing) carries 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 at least tells the agent the returned shape is Bokio's own representation rather than a normalized object. It leaves the actual field set ambiguous and says nothing about size or nulls, so it is complete enough to call correctly but not to predict the response.

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%: invoiceId's provenance ('Id from bokio_list_invoices', not-found behavior) and companyId's fallback to BOKIO_COMPANY_ID are already documented in the schema. The description adds no additional syntax or constraint detail, 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 ('Get one customer invoice by id'), makes the single-record scope explicit, and names the two sibling tools an agent might confuse it with (PDF download, payments). An agent can distinguish this from bokio_list_invoices and bokio_get_supplier_invoice 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?

Explicitly routes the agent elsewhere for PDFs ('Use bokio_download_invoice') and for payment data ('bokio_list_invoice_payments'), which covers the two most likely alternative intents. It does not state when the tool should not be used (e.g., when only a summary of many invoices is wanted), so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and external-dependency semantics are covered. The phrase 'as Bokio returns it' hints at a raw, unnormalized payload, but the description does not elaborate on response shape or failure modes beyond what the schema already says about not-found errors.

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

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

A single short sentence with the resource and lookup key front-loaded; nothing is wasted and no filler remains.

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

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

For a simple two-parameter read tool with full schema coverage and read-only annotations, the definition is nearly sufficient. The only gap is that no output schema exists, so 'as Bokio returns it' leaves the actual returned fields to be discovered at call time.

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%: itemId's origin (from bokio_list_items) and the not-found behavior, plus companyId's BOKIO_COMPANY_ID default, are all documented in the schema. The description adds only the 'artikel' domain gloss, 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 (get) and resource (one item) plus the lookup key (id), and the parenthetical 'artikel' maps it to the Swedish term used in Bokio's domain. It is clearly distinguishable from bokio_list_items by the singular 'one item by id', though it does not name 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?

Usage is implied: fetch a single item when you already have an id, versus listing. There is no explicit statement of when to prefer this over bokio_list_items or what to do if the id is unknown — that guidance lives only in the schema's itemId description.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds little beyond that; 'as Bokio returns it' is vague and does not explain error behavior, permissions, or response shape.

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

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

Two short sentences with no waste. The core operation is front-loaded, followed by the useful alternative.

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

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

For a simple read-by-id tool with full schema coverage and relevant annotations, the description is complete enough. It does not need to explain return values because no output schema exists and the operation is straightforward.

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

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

Schema description coverage is 100%, so both parameters are documented in the schema. The description reinforces that lookup is by id but adds no syntax or format details beyond what the schema already provides.

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

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

The description states a specific verb and resource: get one journal entry by id. It also distinguishes itself from the sibling list tool by naming bokio_list_journal_entries for date-based discovery.

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 directs the agent to use bokio_list_journal_entries when finding entries by date. This gives a clear alternative and the condition that selects it.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that the supplier is returned 'as Bokio returns it' and cross-references supplier invoices, but it does not elaborate on response shape or error behavior beyond what the schema already documents.

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

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

Two short sentences, front-loaded with the core action and followed by a useful sibling cross-reference. There is no redundant or filler text.

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

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

For a simple read-only single-resource getter with full schema coverage and read-only annotations, the description is nearly complete. The only minor gap is that it does not describe the returned supplier shape, though 'as Bokio returns it' signals a raw upstream representation.

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

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

Schema description coverage is 100%, with supplierId and companyId both documented in the schema, including the BOKIO_COMPANY_ID default and not-found behavior. The description's phrase 'by id' adds no meaningful parameter detail beyond the schema, so baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Get one supplier by id.' It also distinguishes the tool from sibling list operations by noting that supplier invoices are retrieved via bokio_list_supplier_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?

It clearly implies retrieval of a single supplier and points to bokio_list_supplier_invoices for a related but separate resource. The schema further establishes that supplierId comes from bokio_list_suppliers, though the description itself does not explicitly state when not to use this tool.

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

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

With readOnlyHint=true already covering the safety profile, the description adds real value: 'as Bokio returns it' signals a raw passthrough with no normalization, and the attachment/download hint is behavior an agent would otherwise only discover by trying it. It doesn't mention error behavior, but the schema already covers the not-found case.

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

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

Two short sentences, front-loaded with the core action and followed by the one non-obvious operational hint. Nothing is wasted.

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

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

For a simple read-only by-id getter with full schema coverage and no output schema, this covers what an agent needs: what it returns (the raw Bokio representation) and how to get the attached file. A brief note on the return shape would push it higher, but that is 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?

Schema coverage is 100% -- both companyId (with BOKIO_COMPANY_ID default) and supplierInvoiceId (id from bokio_list_supplier_invoices, unknown id returns not-found) are fully documented in the schema. The description only restates 'by id' and adds nothing new, so 3 is the correct 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?

Specific verb+resource: 'Get one supplier invoice by id', which cleanly separates it from the sibling bokio_list_supplier_invoices. It also names bokio_list_supplier_invoices' output implicitly as the id source, though it doesn't say so explicitly in the description itself.

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 follow-up sentence routes the agent to bokio_download_upload when an attached file exists, which is a concrete alternative-selection cue. It stops short of stating when not to use this tool (e.g. prefer the list tool for browsing or searching).

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, so safety is covered. The description adds the non-obvious behavioral fact that this returns metadata only and does not stream file contents, which is exactly the kind of scope clarification 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?

Two sentences, no filler, and the core action is front-loaded ahead of the sibling disambiguation. Every sentence 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?

No output schema exists, so the description could name the metadata fields returned; 'metadata' is left abstract. Otherwise, with rich schema coverage and annotations, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, with uploadId's source (bokio_list_uploads) and not-found behavior already documented in the schema. The description's 'by id' repeats that without adding format or semantics, so baseline 3 applies.

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

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

States a specific verb, resource, and scope: 'Get one upload's metadata by id'. It explicitly contrasts itself with bokio_download_upload, so an agent can distinguish the two without opening either schema.

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

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

Names the alternative (bokio_download_upload) and implies the selection rule: use this for metadata, the sibling for file bytes. It doesn't spell out a positive 'use this when...' trigger, but the contrast is clear enough to route correctly.

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

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

Annotations already declare readOnly and openWorld, so the safety profile is covered. The description adds genuine behavioral context beyond that: results are limited to payments created by this integration, and write/creation capability is intentionally absent — both non-obvious traits an agent would otherwise assume.

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 the core operation front-loaded and the scope caveat immediately following. No redundant restatement of the name; every clause carries 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 an output schema, full parameter descriptions, and readOnly/openWorld annotations already present, the description only needs to add the non-obvious scope constraint — which it does. Slightly short of 5 because routing to the sibling get/reconcile tools is left implicit.

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

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

Schema description coverage is 100%, so page, pageSize, query, and companyId are fully documented in the schema. The description only alludes to paging and adds no query syntax or default-fallback detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('List bank payments') plus a paging scope. It distinguishes the list operation from the sibling get_bank_payment by its plural/collection nature, though it never names 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?

The line about creation being 'deliberately not exposed' usefully signals a when-not (don't attempt to create), and the scope note hints at what the tool returns. But it never states when to choose this over bokio_get_bank_payment or bokio_reconcile_bank, leaving alternatives 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?

readOnlyHint=true and openWorldHint=true already cover the safety profile and network behavior, so the description only needs to add context. It adds that results are paged and filterable via a raw query, but says nothing about ordering, result bounds, or error behavior; an output schema covers the return shape.

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

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

Two short sentences, no redundancy: the core capability first, the sibling disambiguation 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?

With full schema coverage, an output schema, and read-only annotations, the description provides enough to call the tool correctly. Its only real omission is disambiguation from the get/download credit-note siblings.

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 page, pageSize, query, and companyId are already fully documented, including the && syntax example and the BOKIO_COMPANY_ID fallback. The description adds only the generic mention of paging and a raw query filter, 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+resource (list credit notes) and even gives the Swedish domain term 'kreditfakturor', which helps agents map to the Bokio API. It explicitly separates itself from bokio_list_invoices, though it does not distinguish against bokio_get_credit_note or bokio_download_credit_note.

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 sentence 'Customer invoices are listed by bokio_list_invoices' is useful routing, but it only rules out a different resource, not the other credit-note tools (get/download). There is no guidance on when to use the query filter vs. plain paging, or on defaults.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that results are paginated and filterable via a raw query, but says nothing about pagination defaults, rate limits, or result shape beyond what the output schema implies.

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 tightly written sentences with zero filler, and the core capability is front-loaded before the sibling routing hint.

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 full schema coverage, an output schema for return values, and annotations covering safety and open-world behavior, the description supplies everything else an agent needs to call this list 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 description coverage is 100%, so page, pageSize, query, and companyId are fully documented in the schema. The description only mentions paging and a raw query filter at a high level, adding no syntax or default details beyond the structured fields.

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

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

The description names a specific verb and resource ('List customers') plus two defining capabilities (paging, raw query filter), and explicitly distinguishes itself from bokio_get_customer for single-record lookups. An agent can select it 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?

It explicitly routes the agent to bokio_get_customer when one customer's details are needed, which is a clear alternative. It does not spell out when to use page vs. query or any exclusions, so it falls just short of the top tier.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the shape of the result (ids, start and end dates), though that is largely repeated by the output schema; it says nothing about pagination, empty results, or company-scoping behavior.

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

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

Two short sentences, front-loaded with the operation and immediately followed by the reason the output matters. No filler.

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

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

With annotations, a fully documented single parameter, and an output schema, the description covers what an agent needs to call it correctly. The only residual gap is the lack of differentiation from bokio_get_fiscal_year.

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 companyId parameter already documents its pattern and the BOKIO_COMPANY_ID default. The description adds no additional meaning about that 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?

States a specific verb and resource ('List the company's fiscal years') plus the fields returned, so the agent knows exactly what it gets. It does not explicitly distinguish itself from the sibling bokio_get_fiscal_year, which is the one ambiguity an agent might have.

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 downstream context: the returned ids feed bokio_download_sie and the fiscalYearId of bokio_account_balances, which tells the agent when this tool is the right entry point. It stops short of saying when to prefer bokio_get_fiscal_year instead.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that results are paged and clarifies the settlement boundary, but it does not describe pagination defaults, ordering, or any other behavioral detail beyond what the schema and annotations provide.

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

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

Two short sentences, front-loaded with the core action and followed by the sibling exclusion. Every sentence carries useful information and nothing is redundant.

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

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

For a straightforward read-only list tool with a full output schema, complete parameter descriptions, and annotations, the description covers the essential scope and the key sibling boundary. Minor pagination details are left to the schema, which is reasonable.

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 input schema. The description adds little parameter-level meaning beyond indicating that the tool operates on one invoice, which is already implied by the required invoiceId in the schema.

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

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

The description uses a specific verb and resource: it lists payments registered on a single invoice. It also explicitly distinguishes itself from bokio_list_invoice_settlements by assigning fees and currency differences to that sibling, so an agent can tell the two apart without opening either schema.

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

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

It clearly scopes use to payments on one invoice and explicitly excludes settlement-related data by pointing to bokio_list_invoice_settlements. It does not cover every possible alternative among the many sibling list tools, but the primary boundary is stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is supplied. The description adds one useful scope caveat about journal-entry revenue, but says nothing about pagination defaults, ordering, or query-field limitations — the schema only documents syntax, not behavior.

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

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

Two sentences, front-loaded with the core operation and immediately followed by the exclusion/alternative. No filler, every clause carries 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 read-only paged list tool with an output schema, full param documentation, and annotations, this covers the key risk of confusing it with ledger/open-item reporting. Minor gap: no note on what the returned invoice records contain or whether credit notes are included, which would help against the credit-note siblings.

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 page/pageSize/query/companyId are fully documented in the schema, including the && filter example. The description only restates 'paging' and 'raw query filter' without adding constraints beyond the schema. 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 ('list customer invoices') plus the two capabilities (paging, raw query filter). It separates the tool from journal-entry-based revenue reporting, though it doesn't distinguish itself from close siblings like bokio_list_supplier_invoices or bokio_list_credit_notes.

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 excludes one case ('revenue booked as journal entries is not listed here') and routes the agent to bokio_account_ledger and bokio_open_items instead. This is real when-not-to-use guidance, though no positive triggers (e.g., when invoicing data is preferred) are given.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds the useful scope constraint (settlements are per-invoice, not account-wide) and names the three settlement kinds. It says nothing about ordering, totals, or whether an invoice with no settlements returns an empty list versus an error, which the schema only partially implies.

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

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

Two short sentences, zero filler: the first defines the resource, the second routes the agent to the sibling. The resource definition is front-loaded ahead of the payoffs.

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?

Output schema exists and the input schema is fully documented, so the description only needs to convey scope and disambiguation, which it does. A minor gap is what a 'settlement' means relative to the invoice balance, but the three enumerated types largely cover it.

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

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

Schema description coverage is 100%, with invoiceId, companyId, page, pageSize, and query all documented in the schema, including the note that an unknown invoiceId returns a not-found error. The description adds no parameter detail beyond that, so baseline 3 applies.

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

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

States a specific verb and resource ('List the settlements on one invoice') and enumerates what a settlement contains: currency differences, bank fees, payment-service fees. This makes the jargon term self-explanatory and separates it from the payments sibling, though it does not explicitly differentiate from other invoice-related tools like bokio_get_invoice or bokio_list_credit_notes.

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 names the alternative for a commonly confused case: 'Payments are listed by bokio_list_invoice_payments.' That is a clear when-to-use-which rule. It stops short of stating prerequisites or when-not to call, but the core routing decision is resolved.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and scope are covered. The description adds the paging trait and clarifies what an item is, but says nothing about ordering, volume, or filtering behavior beyond paging.

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

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

Two short sentences, purpose front-loaded followed by the routing hint. No wasted words.

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

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

Output schema and annotations carry return shape and safety, and the description supplies domain meaning plus the sibling route. Slightly incomplete on pagination defaults and query usage, but nothing an agent needs in order to call 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?

Schema description coverage is 100%, with page, pageSize, query syntax example, and companyId default all documented in the schema. The description only echoes "with paging," so baseline 3 applies.

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

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

States a specific verb and resource ("List items"), defines the domain (products and services used on invoice lines), and notes paging. The parenthetical "artiklar" and the single-item sibling contrast make it easy to distinguish from bokio_get_item.

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: "Use bokio_get_item for one item," which tells an agent exactly when to pick the sibling instead. This is the correct decision rule for a list-vs-get pair.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds that results are paged and filterable, but says nothing about result ordering, default page size, or whether 'query' interacts with or overrides 'from'/'to' — a meaningful ambiguity for a filtered list.

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

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

Two tight sentences, front-loaded with the primary capability and followed by a single routing pointer. No filler, nothing repeated from 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?

An output schema exists, so return values need no explanation, and the six parameters are fully documented in the schema. What remains missing for a paged list tool is ordering and default page size, plus the exact interaction between query and date bounds.

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 six parameters are documented in the schema, giving a baseline of 3. The description adds only that from/to are optional and that query is a 'raw' filter, and the phrasing 'between from and to or narrowed by a raw query filter' hints at an either/or relationship that the schema itself does not state, but it never clarifies 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 and resource ('List journal entries') and includes the Swedish domain term 'verifikationer', which helps disambiguate for users of the Bokio UI. It routes away from bokio_account_ledger, though it does not explicitly contrast with bokio_get_journal_entry.

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 context (paging, date range, raw filter) and names an explicit alternative for the account-postings case: 'For the postings on one account use bokio_account_ledger.' No explicit when-not conditions beyond that, and no mention of when to prefer bokio_get_journal_entry for a single entry.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds that results are paged and that filtering goes through a raw query string, but says nothing about result ordering, defaults, or the shape of the returned collection.

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

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

Two sentences, no filler, with the core purpose front-loaded and the alternative tool routing placed last. Every clause carries 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?

An output schema exists and annotations cover the read-only profile, so return values need not be explained. The description plus routing note is sufficient to call it correctly, though a hint about which fields the raw query accepts would close the last 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 includes a worked query example and page-size bounds, so the schema does the heavy lifting. The description's mention of 'paging and a raw query filter' only mirrors those parameters without adding syntax or constraints of its own.

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

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

States a specific verb and resource ('List supplier invoices') plus the Swedish synonym, and notes paging and a raw query filter. It does not distinguish itself from bokio_list_invoices (customer invoices) or bokio_get_supplier_invoice, relying on the name to carry that, but the resource is unambiguous.

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

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

Explicitly routes the agent elsewhere for a related task: 'For unpaid supplier debt by age use bokio_open_items on account 2440.' That is a concrete when-to-use-something-else rule; it stops short of stating when this tool should not be used (e.g. fetching a single invoice).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered and the bar is lower. The description adds only that results are paged and accept a raw query filter, which is already visible in the schema; it says nothing about sort order, empty-result behavior, or the companyId default beyond the schema.

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

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

Two short sentences, zero filler, and the core purpose is front-loaded before the sibling routing hint. The parenthetical Swedish term earns its place by aiding query matching.

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 annotations, full schema coverage, and an output schema, the definition covers what an agent needs to select and call the tool. Minor room remains: nothing about default company scoping behavior or typical result volume, though the schema covers the former.

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

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

Schema description coverage is 100%, so every parameter including the '&&' query syntax and companyId default is already documented. The description merely names paging and the query filter without adding format or interaction detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('List suppliers') and adds the Swedish term 'leverantörer' so it matches localized user queries. It also routes the adjacent resource away ('Their invoices are listed by bokio_list_supplier_invoices'), making it distinguishable from the supplier-invoice 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 clear usage context by pointing invoices to bokio_list_supplier_invoices, which implies this tool is the supplier-enumeration entry point. It stops short of explicit exclusions such as when to prefer bokio_get_supplier for a single supplier or when to avoid the raw query filter.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that results are paged, which is genuine behavioral context, but says nothing about page limits, total counts, or ordering; details like the 100-item page cap live only in the schema.

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

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

Two sentences, zero filler, with the core operation front-loaded and the redirect to the sibling immediately after. 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?

With a full output schema, complete parameter descriptions, and read-only annotations, the description only needs to establish the listing scope and the download handoff, both of which it does. Minor gap: no guidance on how to paginate through a full result set.

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

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

Schema description coverage is 100%, so every parameter (page, pageSize, query, companyId) is already documented with formats and constraints. The description adds no additional meaning about filtering or company scoping beyond what the schema states, 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+resource: 'List uploaded files and receipts (kvitton) with paging.' The parenthetical synonym and the paging note make the scope unambiguous. It differentiates from bokio_download_upload but does not distinguish itself from the related bokio_get_upload 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?

'Use bokio_download_upload for a file's content' names the alternative and the condition that selects it, which is exactly the routing an agent needs. However, there is no explicit statement of when to reach for listing (e.g. discovering an upload id before downloading), and no exclusion for bokio_get_upload.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, but the description adds substantial behavioral context beyond that: the FIFO exact-öre matching algorithm, that unmatched payments are returned, that items include age in days, that the oldest loaded year's opening balance is presented as one unitemised amount, and the ledger sign convention. This is rich disclosure for a read-only tool.

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

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

The description is three tightly written sentences: purpose and matching semantics first, then return contents, then sign convention. Every sentence contributes useful information 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?

Given that an output schema exists and annotations cover the safety profile, the description is complete enough: it explains the matching logic, what is returned, and how amounts are signed. No critical information 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 description coverage is 100%, so all four parameters are already documented in the input schema, including defaults and examples. The description adds interpretation context (ledger sign, exact-öre matching) but does not add parameter-specific meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource—listing unpaid ledger items at a given date—and includes the distinctive FIFO matching semantics (exact öre). This clearly differentiates it from siblings like bokio_account_ledger (all entries) and bokio_account_balances (balances), so an agent can identify the tool 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?

Usage is implied by the purpose: it is the tool for open items / aging at a point in time. However, the description never explicitly says when to choose this over alternatives such as bokio_account_ledger or bokio_reconcile_bank, nor does it state any exclusions or prerequisites. This is adequate but leaves 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?

Annotations already declare readOnlyHint and openWorldHint, so safety is covered; the description adds non-obvious behavioral context the annotations cannot: results are negated so profit is positive, and amounts follow ledger sign (debit positive, credit negative). This sign convention is exactly the kind of detail that prevents misreading aggregates, though return structure and whether zero-balance classes are included are left 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 short sentences, front-loaded with what gets summed and over what period, then the alternative tool, then the sign convention. No filler and no repetition of schema fields.

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

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

With an output schema present, the description need not explain return shape, and annotations cover the safety profile. All four parameters are documented in the schema, leaving only the aggregation semantics and sign convention for the description, both of which it supplies succinctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description still earns credit by grounding groupBy in accounting meaning (class 3-8 vs. account) and by stating that the period is the aggregation window. The ledger-sign note also clarifies how the aggregated amounts should be interpreted.

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?

"Sum the result accounts (BAS classes 3-8) for a period" states a specific verb, resource, and accounting scope, and the negated-total rule makes the output meaning unambiguous. It explicitly differentiates itself from bokio_account_balances, so an agent can pick it without comparing schemas.

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

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

The description names the sibling to use for the complementary case ("For balance-sheet accounts use bokio_account_balances"), which is a clear routing rule. It stops short of covering edge conditions such as fiscal-year selection or which period boundaries to use, so it is clear context without full exclusions.

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

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

The annotations already establish that this is a read-only, open-world operation. The description adds useful behavior detail: {companyId} substitution and that the response body is returned, but it does not cover error behavior, auth requirements, or pagination implications of arbitrary GET paths.

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 compact sentence that front-loads the main purpose and the key exclusion rule. It contains no filler and remains focused on what an agent needs to select the tool.

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 fully described schema, read-only/open-world annotations, and absence of an output schema, the description provides enough context to call the tool correctly. The remaining gaps, such as error handling and base-path details, are covered by the schema or outside what the description must carry here.

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 path, params, and companyId semantics are already well documented in the schema. The description only adds the {companyId} substitution behavior, which is helpful but does not need to compensate for missing schema detail.

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

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

The description states a specific verb and resource: send a GET to any Bokio API path. It also distinguishes this tool from siblings by framing it as the escape hatch for paths that no other tool covers.

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 this tool for paths no other tool covers, which gives clear guidance against reaching for it when a dedicated sibling exists. It does not enumerate specific alternatives, but the exclusion rule is stated directly.

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, yet the description goes well beyond them: greedy earliest-match algorithm, ledger-line-used-once constraint, output composition (matched pairs, unmatched both sides, suspected duplicates, totals), and the difference = ledger minus bank sign convention. This is rich behavioral context 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?

Dense and front-loaded with the matching semantics first, then outputs and sign convention. Slightly run-on across two long sentences, but every clause carries substantive information for a nontrivial algorithm.

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 matching tool with an output schema and annotations covering safety, the description supplies everything needed to call and interpret it: algorithm order, tolerances, output structure, and sign conventions. Little is left ambiguous.

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 meaning by explaining how toleranceDays governs matching ('earliest unmatched ledger line within toleranceDays') rather than just restating the field, plus the ledger-sign convention for amounts. It still doesn't elaborate account/companyId defaults beyond the schema.

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

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

States a specific verb and resource: matching bank statement rows against a ledger account. The mechanism ('reading the SIE export itself') and scope are clear, letting an agent distinguish it from siblings like bokio_list_bank_payments or bokio_find_duplicates.

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 matching workflow and toleranceDays behavior are described, implying when the tool applies, but no explicit 'use this instead of X' routing or prerequisite context is given relative to siblings such as bokio_account_ledger or bokio_find_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?

Goes well beyond the readOnly/openWorld annotations by disclosing the ledger sign convention (debit positive, credit negative), that outputVat is negated, how netVat is derived, and when it is positive. It also warns that the figures are raw account totals rather than tax-return boxes, which prevents a costly misinterpretation.

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

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

Every clause carries non-obvious information: the account ranges, the negation rule, the netVat formula, the interpretation caveat, and the sign convention. The core scope statement is front-loaded and there is no filler.

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

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

An output schema exists, yet the description still supplies the accounting semantics an agent needs to read the numbers correctly. For a read-only, three-parameter aggregation tool this covers everything required to invoke 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%, with both date bounds and the companyId fallback already documented in the schema. The description only adds the loose phrase 'for a period', 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 (Sum) plus the exact account ranges (2610-2659, 3000-3999) and the derived figures it computes. That precision distinguishes it from generic siblings such as bokio_account_balances and bokio_profit_and_loss without needing to name them.

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

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

Usage is only implied: the caveat 'do not map to tax-return boxes' tells an agent this is for VAT balance inspection rather than tax filing, but there is no explicit when-to-use statement or named alternative for cross-checking VAT.

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