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

Annotations already declare readOnlyHint=true and destructiveHint=false, so 'Read-only' in the description adds nothing. The description does disclose what the sweep looks for, which is genuine behavioral context, but says nothing about how much work it performs, what happens when maxVouchers is hit, or whether results are truncated — all material for an openWorld sweep.

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

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

A single front-loaded sentence: the action and outcome come first, then the defect inventory. Every clause names a distinct detection category, so the length is earned rather than padding, though the list runs long enough that an agent must parse carefully.

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

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

There is no output schema, so the description must carry return-value semantics, and it only does so indirectly by naming the problem categories. It never says what a finding looks like (per-voucher list? severity? counts?), nor what happens with an unbounded period sweep — enough missing for a complex, open-world audit tool to be a real 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%, so every parameter (from, to, maxVouchers, includePositions) is already documented in the schema with formats, defaults and trade-offs. The description mentions none of them; baseline 3 applies since the structured data carries the full load.

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?

A specific verb+resource ('Sweep vouchers and flag VAT problems') followed by an enumeration of the exact defect classes it detects (wrong taxRule for foreign suppliers, revenue rules on expense vouchers, rate/rule mismatches, arithmetic errors, supplier inconsistency). This is far more concrete than a generic 'audit' label. It does not, however, acknowledge the overlapping sibling sevdesk_reverse_charge_report, which an agent could easily confuse with this 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?

Usage is implied by the defect list — you would call it before filing VAT returns or when reconciling suppliers — but there is no explicit 'use when'/'do not use when' framing and no routing to alternatives such as sevdesk_reverse_charge_report or sevdesk_find_duplicates. The 'Read-only' note signals it is a safe inspection step, but the agent must infer the scenario.

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?

Discloses far more than the annotations: read-only refusal under SEVDESK_READ_ONLY, describe-only behavior under dry-run, the preventSendBy=true default for *GetPdf reads, the non-obvious fact that some GETs mutate, and that DELETE is irreversible. This is exactly the context annotations alone (destructiveHint, openWorldHint) cannot convey.

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

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

Front-loads the core dispatch mechanic, then the safety/dry-run rules, then the warning — a sensible ordering. Every sentence carries distinct information, though the preventSendBy and GET-that-writes sentences are packed tightly enough to need a second read.

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 generic open-world dispatcher with an output schema absent, the description covers the request-construction and safety model thoroughly. It does not indicate what a response looks like or how errors surface from arbitrary operations, which is the remaining gap given there is no output 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 coverage is 100%, so baseline is 3, but the description adds real semantics the schema lacks: param-name-to-path substitution, leftover params becoming query params, and bracket syntax for nested objects. The only gap is that `body` handling is left implicit for a nested-object tool.

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 mechanic ("Execute any operation from the catalogue" plus how params map to path/query), so an agent can tell this is the generic dispatcher rather than a task-specific sibling like sevdesk_create_invoice. It never names the catalogue source (sevdesk_list_operations) or the alternative inspector (sevdesk_describe_operation) in the prose, relying on the schema for that routing.

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?

Explains operative conditions (read-only server refuses mutations, dry-run only describes) which is genuinely useful selection context, but gives no when-to-use-this-vs-dedicated siblings guidance. An agent has to infer that dedicated tools should be preferred and that operationId must be discovered first.

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

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

Annotations already declare readOnly=false and destructive=false, and the description earns credit for adding that the record is forced to draft status 50 and that SEVDESK_DRY_RUN is honored — real behavioral facts not in structured data. The 'can change data' warning is somewhat redundant with the annotations, and return details are absent.

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

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

Two sentences plus a warning marker, with the draft-status constraint front-loaded. No filler or repetition of the title.

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

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

For a mutating create tool the description covers safety posture (draft-only), dry-run behavior and key side effects, and annotations carry the rest. No output schema exists, so a description of the returned invoice id would have helped an agent know what to expect 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 coverage is 100%, so the baseline is 3; the description goes further by summarizing what positions carry and disclosing that the contact's address is auto-filled, cross-linking contactId to a side effect. It doesn't touch dryRun or invoiceDate semantics, but the schema covers those well.

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

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

States a specific verb and resource ('Create an outgoing invoice') plus the exact resulting state ('as a draft (status 50)'), which separates it cleanly from sevdesk_create_voucher (incoming) and sevdesk_mark_invoice_sent. An agent can pick this without opening any schema.

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

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

Explains the operating context clearly — always a draft, nothing reaches the customer without review — which tells the agent when this tool fits. It stops short of naming an alternative (e.g. how to finalize/send afterwards), so it lacks explicit routing to siblings.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, but the description adds real context: the draft-by-default safety behavior, the warning that it changes data, and the domain pitfall that expense reverse charge is 12/13/14 rather than 5. It does not cover permission requirements, duplicate-voucher risk (despite a sevdesk_find_duplicates sibling), or what the call returns, so it stops short of a 5.

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

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

Front-loaded with the core action and endpoint, then constraints, then escalation path — a sensible reading order with little waste. The closing '⚠️ This tool can change data in sevDesk' is partially redundant with the earlier 'WRITE operation' flag, a small duplication that keeps it from a 5.

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

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

For an 11-parameter tool with nested line items and no output schema, the description supplies the workflow prerequisite, the safety default, and the override path. The remaining gap is that it never says what a successful call returns (e.g. the new voucher id) or how a created draft should be verified or finalized afterward.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by adding meaning the schema does not: taxRuleId must never be guessed and must come from receipt_guidance, and expense rules pair with creditDebit C while revenue rules pair with D. The status default rationale is also explained rather than merely restated.

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 plus the exact endpoint ('Create a voucher via /Voucher/Factory/saveVoucher'), which separates it cleanly from sevdesk_create_invoice and the list/get voucher siblings. It also bounds its own scope by naming the fallback path (sevdesk_call) for anything the wrapper doesn't cover.

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 to check sevdesk_receipt_guidance first, explains the default status 50 exists so nothing is booked without review, and names the alternative (sevdesk_call with operationId 'voucherFactorySaveVoucher') for uncovered cases. When-to-use, prerequisite ordering, and escape hatch are all present.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value by disclosing what the call returns (parameter list, request-body shape, example call) and framing it as a prerequisite step. It stops short of saying whether the spec is live or cached, or anything about auth.

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

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

Two sentences, both load-bearing: the first says what comes back, the second says when to use it. The usage rule is front-loaded as an imperative, which is the right emphasis for a lookup 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?

With no output schema, the description carries the burden of describing return values and does so adequately by enumerating the three artifacts returned. For a one-parameter, open-world spec lookup this is nearly complete; only the freshness/source of the spec is unstated.

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

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

Schema description coverage is 100% and the operationId field already says it must be the exact ID as returned by sevdesk_list_operations. The description only restates 'one operationId', adding no format or sourcing 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: shows the parameter list, request-body shape and an example call for a single operationId. The reference to sevdesk_call helps an agent separate it from the actual invocation, though it never explicitly contrasts with sevdesk_list_operations, which is the closest lookalike.

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?

'Always do this before sevdesk_call on an operation you have not used before' gives an explicit trigger condition and names the alternative tool it precedes. Nothing about when to reach for this versus the siblings is left to inference.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, open world), and the description usefully confirms it reads the filesystem but never writes and that sevDesk access is read-only. It additionally discloses the matching heuristic and expected filename formats, which are genuine behavioral traits beyond the annotations; only the output shape and cap-flagging behavior are left thin.

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

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

Front-loaded with the core comparison, then matching rules and safety statement; every sentence carries information. Slightly dense, but no filler.

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

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

For a seven-parameter diff tool with no output schema, the description supplies the essential context: what is compared, both output directions, how matching works, and read-only guarantees. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so a baseline of 3 is already earned. The description adds real value by explaining the matching strategy that governs dayTolerance and #reference parsing, plus concrete filename examples that tell the agent how files are 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?

States a specific verb and resource: compares a local receipt folder against sevDesk vouchers and reports missing files and missing vouchers. This is clearly distinct from siblings like sevdesk_list_vouchers or sevdesk_find_duplicates, and 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?

The description makes clear when the tool applies: comparing a local PDF folder against booked vouchers, with the matching precedence (#reference first, then date + amount) spelled out. It does not name an alternative sibling or state exclusions, but the context is unambiguous.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with "Read-only." It adds real behavioral substance by defining the matching heuristics that determine what counts as a duplicate, though it says nothing about how large the scan is or what the response contains.

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

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

Two tight sentences: the detection scope comes first, the read-only safety note last. No filler, no repetition of the title.

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

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

With no output schema, the description could say more about the shape of the duplicate report, but it covers both detection modes, the read-only guarantee, and the parameters are fully schema-documented. Adequate for an agent to call it correctly.

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

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

Schema coverage is 100%, so all four parameters are documented in the schema itself. The description still adds meaning to dayWindow by explaining the duplicate-matching purpose behind the day tolerance, going slightly beyond a pure restatement.

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

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

Names a specific verb ("Detect") and resource (vouchers), and spells out the exact duplicate criteria (same document number, or same supplier + amount within a few days) plus a second check for Entwurf/offen vouchers. This is clearly distinguishable from siblings like sevdesk_list_vouchers or sevdesk_diff_receipt_folder, which enumerate or compare rather than detect 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 intent (find duplicate and stuck vouchers) implies when to reach for it, but the description never states when not to use it or names an alternative sibling for adjacent tasks such as reconciling transactions or listing vouchers. Usage is inferable rather than guided.

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 beyond annotations meaningfully: it clarifies that although a file is written to the local filesystem, the tool never mutates the invoice's send state (preventSendBy) and is read-only towards sevDesk. This resolves the potential confusion between a local disk write and a remote mutation.

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

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

Two short sentences, front-loaded with the core action and followed by the key behavioral caveat. 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?

For a simple two-parameter tool with no output schema, the definition is nearly complete. Minor gap: it doesn't state the returned filename or path, which an agent might need for follow-up operations, but this is small.

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 documented in the schema. The description adds the allowlist constraint for `directory`, but nothing extra for `invoiceId`. Baseline 3 is appropriate when the schema carries the parameter semantics.

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

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

Specific verb+resource: 'Fetch the rendered PDF of an invoice and save it into a directory'. Clearly distinguishes from siblings like sevdesk_mark_invoice_sent or sevdesk_list_invoices, which do not produce a PDF artifact.

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

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

States the precondition that the target directory must come from the SEVDESK_RECEIPT_DIRS allowlist, and reinforces it via the 'preventSendBy' note. No explicit alternative routing (e.g. when to use a download vs. upload path), but the usage context 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, destructiveHint=false and openWorldHint, so 'Read-only' adds little. The valuable addition is that VAT treatment and per-position tax rates are returned decoded rather than as raw codes, which tells the agent how to interpret output and is not derivable from the annotations or 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?

Front-loaded single sentence that covers scope, contents, and transformation behavior, followed by a short safety tag. The trailing 'Read-only.' duplicates the readOnlyHint annotation, a small redundancy but nothing else is wasted.

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

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

With no output schema, the description must convey return shape, and it does name the key contents (line items, decoded VAT treatment, per-position tax rates). It stops short of describing behavior on a missing or invalid voucher id, which is the main remaining gap for a single-record getter.

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, voucherId, already documented at 100% schema coverage as 'Numeric voucher id.' The description adds no format, range, or error semantics beyond that, so the schema carries the load and 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?

A specific verb (Fetch) plus resource (a single voucher) and an explicit statement of what comes back (line items, VAT treatment, per-position tax rates). The word 'single' implicitly separates it from sevdesk_list_vouchers, but no sibling is named, so differentiation is inferred rather than stated.

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

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

Usage is only implied: an agent can infer this is the detail-fetch counterpart to the list tools when full position-level data is needed. There is no explicit when-to-use, when-not-to-use, or named alternative such as sevdesk_list_vouchers.

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=true, destructiveHint=false), and the added method detail — buckets computed from invoice date plus payment terms — is genuine behavioral context beyond the schema. It also discloses that drafts and send-mark-missing invoices are included, which is non-obvious scope. It stops short of 5 by omitting performance/volume characteristics for an openWorldHint endpooint and any ordering of returned rows.

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

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

Front-loaded with the business question ('Who owes you money and for how long'), then the composition of the report, then the read-only marker. It is a single dense sentence-list with little waste, though the long comma chain makes the enumeration slightly harder to parse than separate clauses would.

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 must convey the shape of the result, and it does: bucket dimensions, per-invoice remainder, and the two edge categories. Missing details are secondary (currency/total handling, sort order, whether bucket thresholds like 30/60/90 are fixed), which keeps it below 5.

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

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

Schema coverage is 100%, so 'to' (period end), 'from' (invoice date), and maxItems are already documented with formats and the default cap. The description adds no parameter-level detail beyond what the schema carries. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description states precisely what the tool produces: open and partially-paid invoices bucketed by days overdue, outstanding remainder per invoice, unsent drafts, and invoices missing a send mark. That is far more specific than a bare 'invoice aging' restatement. It never names a sibling (e.g. list_invoices vs this aging report), so it falls short of a 5 on sibling differentiation.

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

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

Usage is implied by the output it promises (aging/receivables reporting) rather than stated. There is no explicit 'use this when…, use list_invoices instead for…' routing, and no prerequisites or exclusions. An agent can infer the use case but must guess the boundary against sevdesk_list_invoices and sevdesk_summarize.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so 'Read-only' largely repeats structured data. The description adds useful scope by clarifying that contacts are customers and suppliers, but it does not mention pagination behavior, filtering expectations, or return characteristics beyond what the schema already covers.

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 short sentences with no wasted language, and the core purpose is front-loaded. It is appropriately sized for a simple list tool whose schema and annotations carry most of the operational detail.

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

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

For a simple read-only list tool with full schema descriptions and clear annotations, the description is mostly complete. The absence of an output schema means return shape is not described, but the essential purpose and scope are covered.

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 already carry clear documentation, including limit and maxItems semantics. The description adds no parameter-specific detail, which is acceptable but provides no extra value over the schema.

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

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

The description states a specific verb and resource ('List customers and suppliers') and makes clear that contacts include both customers and suppliers. It is distinguishable from sibling list tools by resource, though it does not explicitly compare itself to alternatives.

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

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

There is no guidance on when to use this tool versus alternatives such as sevdesk_find_duplicates or other list tools. The description implies a basic listing use case but gives no conditions, exclusions, or prerequisites.

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 destructiveHint=false, so 'Read-only.' adds nothing. The one genuinely useful disclosure is the shape of returned records (number, customer, sums, status, dates), which substitutes for the missing output schema, but nothing is said about pagination or how the fetch cap affects completeness.

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

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

One front-loaded sentence plus a two-word tag; no filler. The trailing 'Read-only.' is redundant with the annotations and slightly dilutes conciseness.

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 4-param filter tool with no output schema, listing returned fields is a meaningful contribution. Still absent is any statement about result volume behavior (limit default 200 vs maxItems default 2000) or ordering, which an agent needs to interpret results correctly.

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

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

Schema description coverage is 100%, so baseline 3 applies. The description does not discuss from/to, limit, or maxItems semantics—in particular the distinction between the row limit and the fetch cap—leaving that entirely to the schema text.

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

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

Specific verb+resource: 'List invoices you issued' with an enumeration of returned fields. 'Issued' implicitly separates it from vouchers/transactions siblings, but there is no explicit contrast with sevdesk_list_vouchers or sevdesk_summarize, so differentiation relies on inference.

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

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

Usage is implied by the name and the field list (fetch issued invoices), and 'Read-only' signals a safe read path. However, there is no explicit when-to-use guidance, no mention of when to prefer sevdesk_list_vouchers/sevdesk_summarize, and no note on when date filters are needed.

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

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

Annotations already establish readOnly, non-destructive, open-world, so the safety profile is covered. The description adds real context beyond that: it discloses the catalogue size (151 operations), the pinned API version, and the fact that results carry operationIds, which matters because no output schema exists. It stops short of describing result shape or pagination behavior beyond the limit parameter.

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

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

Two sentences, front-loaded with the purpose before the tag enumeration. The tag list is somewhat redundant with the enum in the schema and inflates length, but it does let the agent scan available resources without opening the schema.

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

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

With no output schema, the description carries the burden of indicating return value, and it does so by framing the result as an operationId lookup and by implying path/summary fields via the query parameter. Combined with full parameter documentation and rich annotations, an agent has enough to call it correctly; only the downstream describe/call handoff and result shape are unstated.

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

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

Schema description coverage is 100% and each of the four parameters is documented in the schema, including enum meanings for tag and kind and the default/max for limit. The description only repeats the tag enum list, adding no syntax or format meaning beyond structured data, 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 gives a specific verb (search) and resource (sevDesk API catalogue, 151 operations, API 2.0.0) and states the concrete output the agent needs: an operationId. It also carves out its niche relative to the dedicated sibling tools ('anything not covered by a dedicated tool'), which is what makes it distinguishable.

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

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

It clearly states the condition that selects this tool (no dedicated tool covers the resource), which implicitly excludes the many dedicated siblings like sevdesk_list_vouchers or sevdesk_get_invoice_pdf. It does not name the natural follow-on siblings (sevdesk_describe_operation, sevdesk_call), so the agent must infer the list-then-describe-then-call workflow.

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 destructiveHint=false, and the description's 'Read-only' merely restates that. No added behavioral context is provided on pagination defaults, how limit versus maxItems interact, or what happens when filters match nothing, which is the information an agent actually lacks.

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, front-loaded sentences with no filler. The only wasted clause is 'Read-only', which duplicates the annotation rather than adding anything.

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

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

For a five-parameter, zero-required read tool with fully documented schema and clear annotations, this is sufficient to call correctly. The remaining ambiguity, filter-then-limit interaction, is covered by the parameter descriptions themselves.

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

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

Schema description coverage is 100%, so the baseline is 3. The description hints at account and period filtering, but it does not clarify the non-obvious distinction between 'limit' (rows returned) and 'maxItems' (rows read before filtering), which is the one place prose could have added value.

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

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

The description gives a clear verb+resource ('List bank transactions') and scopes it with optional account and period filters. It does not, however, distinguish itself from the closest sibling, sevdesk_reconcile_transactions, leaving the agent to infer the boundary from the name alone.

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

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

'Optionally for one account and period' implies when the filters are useful, but there is no explicit when-to-use/when-not guidance and no named alternative (e.g., reconcile_transactions for matching against vouchers). Usage is inferable rather than 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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered; 'Read-only' in the description is redundant. It does add real value by disclosing which fields come back, which matters since there is no output schema. However, the two-tier retrieval behavior implied by 'limit' vs 'maxItems' (rows returned vs records fetched before filtering) is not explained anywhere, and that is exactly the kind of behavioral nuance the description should surface.

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

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

A single front-loaded sentence with an efficient colon-delimited field list; nothing is buried or padded. The trailing 'Read-only' is the one wasted clause since it duplicates the annotations.

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

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

With no output schema, the field enumeration is a valuable addition and carries the return-value burden reasonably well. But for a six-parameter, zero-required listing tool with a non-obvious fetch-cap vs row-limit distinction, the description leaves an agent guessing about the maxItems/limit interplay and about paging strategy.

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

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

Schema coverage is 100%, so all six parameters are already documented in the schema, which sets the baseline at 3. The description's field list gestures at date/supplier/status filtering but adds no syntax, default, or interaction detail beyond what the schema provides.

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

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

Specific verb + resource ('List incoming/outgoing vouchers') plus a concrete enumeration of the returned fields (date, supplier, gross/net/tax, status, decoded VAT treatment), which makes the tool's scope tangible. It does not explicitly differentiate itself from close siblings such as sevdesk_list_invoices, sevdesk_list_transactions, or sevdesk_get_voucher, so it stops short of a 5.

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

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

The description never states when to reach for this tool versus sevdesk_list_invoices, sevdesk_list_transactions, or sevdesk_get_voucher, despite that being the main selection ambiguity in this sibling set. 'Read-only' is the only routing hint and it merely restates the annotation, not a usage condition.

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 a non-read-only, non-destructive, open-world mutation; the description adds real value on top by clarifying no email is dispatched, that enshrined invoices are rejected, that the result is verified, and that a dry-run environment flag is respected. It does not say whether the state change is reversible or how the verification surfaces.

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, front-loaded sentences plus a warning tag, with no filler. Minor deduction because 'enshrined invoices' is unexplained jargon the agent must guess at.

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 three-parameter mutation with no output schema, the description covers purpose, failure condition, no-email scope, verification and dry-run handling. The remaining gaps — reversibility, idempotency, and what 'verifies the result' returns — are small but non-trivial for a state-changing call.

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

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

Schema description coverage is 100%, so the schema already defines all three parameters, which sets the baseline at 3. The description does add meaning to the cryptic enum codes by translating VPDF/VPR/VP into PDF download, print and postal, but offers nothing on invoiceId or dryRun.

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 ('Mark an invoice as sent') and immediately scopes it with 'without emailing anything', plus the meaningful send-type modes. It implicitly distinguishes itself from email-sending and PDF-fetching siblings, though it never names an alternative tool outright.

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

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

Gives a clear exclusion rule ('refuses enshrined invoices') and a dry-run path ('Honors SEVDESK_DRY_RUN'), which tells the agent when the call will fail and how to preview safely. It stops short of naming which sibling to use instead when an invoice is enshrined or when email really is needed.

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

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

Annotations already establish readOnly/openWorld/non-destructive, so the description's added value is disclosing what the call reports: token validity, server mode, and tax-system generation. That is genuinely useful context an agent could not infer from the empty 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, front-loaded with the verb and the reported facts, ending with the imperative usage cue. Nothing wasted.

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

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

With no output schema, the description is the sole source of return-value expectations and it names the three things reported. It could add what a failure result looks like, but for a diagnostic ping it is close to complete.

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

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

Zero parameters, so the baseline is 4; the description correctly adds no param narrative since none exist.

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 specific verbs and outputs: verify the API token, report server mode, and bookkeeping generation (1.0 taxType / 2.0 taxRule). This is unmistakably the connection/diagnostic tool versus the domain-operation siblings like sevdesk_list_invoices or sevdesk_call.

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?

"Run this first" gives clear, actionable timing guidance that distinguishes it from every sibling. No when-not or failure-path guidance is given, but for a preflight check that guidance is largely implicit.

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 destructiveHint=false, so safety is covered. The description adds genuinely new behavioral detail: output is capped and 'never the full account dump,' warning the agent that absence of a result does not mean the account does not exist — a meaningful disclosure beyond the annotations.

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

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

A single dense but front-loaded sentence that leads with what the table is and follows with filtering and the output cap; no filler. The em-dash construction is slightly heavy but every clause contributes 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 five-parameter, all-optional read tool with full schema coverage and no output schema, the description covers purpose, filtering and the key output cap. It could note that unset filters default to the expense side and 20 rows, but nothing critical to 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 all five parameters are documented in the schema itself, and the description merely echoes 'filter by text, account number or tax rule' without adding format or interaction semantics. It omits the side and limit parameters entirely; baseline 3 is appropriate when the schema carries the load.

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

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

States a specific resource (sevDesk's booking/DATEV-SKR account guidance table) and what it contains (accounts per side plus the tax rules and rates each allows). It is clearly distinguishable from siblings like sevdesk_set_tax_rule or sevdesk_audit_vat, which mutate or analyze rather than look up the reference table.

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

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

The phrase 'the table sevDesk validates against when a voucher is booked' implies the lookup context (checking valid accounts before/while booking), which is useful implied usage. However, it never explicitly says when to call this versus sevdesk_set_tax_rule or sevdesk_get_voucher, nor does it state any exclusions or prerequisites.

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 destructiveHint=false, yet the description still adds real value by disclosing the heuristic nature of the matching and the two-directional output semantics. 'Read-only' repeats the annotation but does not contradict it.

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

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

Three tight sentences, front-loaded with the core action, then scope, then the interpretive caveat. 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?

With no output schema, the description works hard by signaling the result is a checklist of findings rather than a verdict. It could go slightly further in describing the shape of returned match/unmatched items, but it is sufficient for correct invocation.

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

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

Schema coverage is 100%, so parameters (from, to, maxItems, dayWindow) are fully documented by the schema. The description only alludes to date proximity, adding no extra meaning such as default window behavior or cap semantics. Baseline 3 applies.

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

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

States a specific verb (match/reconcile) and resource pair (bank transactions vs vouchers), plus the matching criteria (amount and date proximity). Distinct from siblings like sevdesk_find_duplicates or sevdesk_list_transactions, which do not cross-reference the two sets.

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?

Clearly frames both reporting directions — unmatched payments and uncovered non-draft vouchers — and warns that results are a heuristic checklist. It stops short of naming explicit alternatives or when not to use it (e.g. use find_duplicates for exact duplicates).

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint, so the trailing 'Read-only' is largely redundant. The description does add real domain behavior — nets-to-zero vs actually-payable VAT, and a separate lookalike list — but never says what happens when maxVouchers is reached (error vs silent truncation of the totals), which is the main behavioral risk for a report tool.

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

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

Three sentences, front-loaded with the core total before the categorization detail and the anomaly caveat. Dense and efficient; the only waste is the redundant 'Read-only' closer already covered by annotations.

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

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

No output schema exists, and the description does carry the return shape: a total split into three categories plus a separate list of mis-booked vouchers. What's missing is the truncation/edge behavior of the safety cap and any indication of how the result is formatted or defaulted when no period is supplied (no required parameters).

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 from/to formats, the 0-100 rate default of 19, and the 2000 safety cap are all already documented in the schema. The description only restates 'for a period' and adds no semantics the schema lacks, 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?

Specific verb-plus-resource ('Total the reverse-charge (§13b) tax base for a period') with an explicit breakdown into three tax-rule categories and an anomaly list. The §13b/13b-specific framing effectively separates it from generic siblings like sevdesk_audit_vat, though no sibling is named.

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 (period-based §13b reporting) rather than stated: no when-to-use sentence, no exclusion, and no routing versus sevdesk_audit_vat or sevdesk_summarize. The 'vouchers that look like they belong but are not booked that way' clause hints at the audit context but doesn't tell the agent when to pick this over the alternatives.

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

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

Goes far beyond the annotations: discloses guardrails (refuses enshrined vouchers and wrong-side rules), post-hoc verification, dryRun preview, that positions keep their rates, and the subtle paid foreign-currency recalculation behavior. The 'can change data' warning aligns with readOnlyHint=false and does not contradict destructiveHint=false (it mutates but does not delete).

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

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

Front-loads the action and the guardrails before the caveats, and every sentence carries substantive information. The parenthetical example and warning add density but remain justified; slightly long for a three-parameter 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?

Covers the mutation semantics, preconditions, and verification behavior thoroughly for a write tool with no output schema. It does not describe what the verification returns or the response shape, but the essential call-decision information is present.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it clarifies that dryRun previews the request, that taxRuleId must come from the correct side of the books, and that rates on existing positions are preserved. It does not enumerate the enum values, which the schema already covers.

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 ('Rebook a voucher onto a different VAT rule') with a concrete example mapping to taxRule 12. This is clearly distinguishable from the read-oriented siblings like sevdesk_get_voucher and sevdesk_audit_vat.

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 states when it applies (draft vouchers only) and when it does not (booked/paid vouchers, enshrined vouchers, rules from the wrong side of the books), and routes the agent to the UI for paid vouchers. This is exactly the when/when-not/alternative guidance the dimension rewards.

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, destructiveHint=false and openWorldHint=true, so the trailing 'Read-only' sentence adds nothing. What the description does add is the behavioral heuristic (a supplier recurring across N months with a missing month is flagged), which helps the agent interpret results, but it doesn't disclose scanning cost or the meaning of the maxVouchers safety cap.

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

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

Front-loaded with the core action, with a compact concrete example that earns its place. The closing 'Read-only.' is redundant with the annotations and is the only wasted clause.

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

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

With no output schema and fully documented parameters, the description gives enough for correct invocation: the detection semantics, an illustrative result pattern, and a safety profile. Only the shape of the returned report (per-supplier list of missing months?) 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 all four parameters are documented in the schema with formats, ranges and defaults. The description mentions 'monthly cadence' but never ties it to minMonths or explains how maxVouchers limits the scan, so it adds essentially nothing beyond the schema — baseline 3.

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

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

States a specific verb and resource: detect suppliers that bill on a monthly cadence and report months missing a voucher. This is clearly distinct from siblings like sevdesk_find_duplicates or sevdesk_diff_receipt_folder, and the worked example (March, April, June but not May) makes the output target unambiguous.

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

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

Usage is implied by the example — the tool finds missing receipts — and the read-only nature is stated. However, it never says when to prefer this over alternatives such as sevdesk_list_vouchers or sevdesk_reconcile_transactions, nor does it state preconditions or when the tool is not appropriate.

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 destructiveHint=false, and the description reinforces rather than contradicts that ('Read-only'). It adds a genuinely useful non-obvious trait: the response stays small regardless of ledger size, and rows are never returned — the key behavioral difference from the list tools. It does not mention the fetch-cap trade-off or what happens when maxItems truncates the aggregation, which the schema alone 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 dense sentences: the core behavior (aggregate, no rows, which sums) is front-loaded, followed by routing guidance and the size guarantee. No filler, and every clause carries information an agent needs to choose 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?

For a 7-parameter read tool with no output schema, the description still explains what the response contains (counts, net/tax/gross sums, grouped buckets), which is the information an output schema would otherwise provide. Combined with 100% schema coverage and safety annotations, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so every parameter including enums and defaults is already documented, and the description mostly restates the grouping options. It adds the framing that grouping can be by 'nothing' for a single total, but no date-format, cap, or side semantics 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 (aggregate), specific resources (invoices or vouchers), and the defining constraint (counts plus net/tax/gross sums, never rows). It also names the enumeration of grouping dimensions, so an agent can distinguish it from every list_* sibling 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 says to use this for totals instead of the list tools, and supplies concrete example intents ('revenue in Q2', 'expenses by supplier'). The alternative (sevdesk_list_invoices / sevdesk_list_vouchers) is named implicitly by category and the selection condition is 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?

Annotations already declare readOnlyHint=false, openWorldHint=true, and destructiveHint=false, so the safety profile is mostly covered. The description adds useful context beyond annotations: it is a WRITE operation, is refused under SEVDESK_READ_ONLY, targets temporary voucher storage, and returns a token for sevdesk_create_voucher.

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 front-loaded with the purpose and workflow in the first sentence, followed by the write-operation warning. It is brief, structured, and every sentence contributes useful selection or safety 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?

Although there is no output schema, the description explains the key return value: a filename token to pass to sevdesk_create_voucher. With the schema fully documenting the three parameters and annotations covering safety hints, the description is complete enough for correct invocation.

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

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

Schema description coverage is 100%, so filePath, mimeType, and dryRun are already documented in the schema. The description does not add parameter-level detail beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource: upload a local PDF/image/XML e-invoice to sevDesk temporary voucher storage. It also names the downstream sibling, sevdesk_create_voucher, so the agent can distinguish this preparatory upload step from voucher creation 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?

Usage is clearly implied: call this to upload a local file and obtain a filename token, then pass that token to sevdesk_create_voucher. It also notes the SEVDESK_READ_ONLY refusal condition, but it does not explicitly state when not to use this tool or name alternative upload paths.

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