brandbill

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

Annotations already flag destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely new behavioral facts: cancellation immediately spawns a numbered Stornorechnung, is irreversible, and leaves already-received payments with the customer — a real financial consequence not encoded anywhere else.

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 clauses, front-loaded with the action, then the side effect, then the irreversibility warning. No filler; every sentence carries distinct information.

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

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

For a destructive two-parameter mutation with no output schema, the description covers the key unknowns: side effect, reversibility, and payment implications. Only the parameter-level meaning and any permission requirements are left unaddressed.

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

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

Schema coverage is only 50%: 'id' is described tersely as 'Beleg-ID' and 'reason' has no description at all. The description mentions neither parameter, so it does not compensate for the gap — an agent gets no help on what 'reason' is used for or whether 'id' refers to the invoice or another document type.

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

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

Names a specific verb and resource ('Ausgestellte Rechnung vollständig stornieren') and immediately explains the mechanism: a Stornorechnung with its own number is issued. This is more specific than the title alone, though it does not explicitly contrast with the sibling create_credit_note, which is the closest alternative.

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

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

'Ausgestellte Rechnung' implicitly scopes usage to already-issued invoices (not drafts, cf. delete_draft), and 'Nicht rückgängig zu machen' signals caution. However, there is no explicit guidance on when to cancel vs. issue a credit note via create_credit_note — the most relevant routing decision an agent faces here.

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, destructive=false, idempotent=false, none of which the description contradicts. The description adds genuinely new behavioral facts: the result is a draft, and the source quote is mutated to 'accepted' — a side effect on another record that no annotation conveys. Missing only auth/permission notes.

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 compact sentences: action and outcome first, optional parameter second, required follow-up last. No filler and nothing buried.

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

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

With no output schema, the description implies a draft is produced but doesn't say what is returned (new document ID? draft object?) for chaining a finalize_document call. Otherwise the mutation semantics, optional parameter and sequencing 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 coverage is only 50% and the 'quantities' property has no schema description, so the description's '{Angebotspositions-ID: Menge}' mapping is essential and well explained. For 'id', the phrase 'aus einem ausgestellten Angebot' narrows the generic 'Beleg-ID' to the quote record, though it never states the expected ID type explicitly.

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 pair: turn an issued quote (Angebot) into an invoice draft, and adds the side effect 'markiert es als angenommen'. This clearly separates it from siblings like create_document (generic creation) and finalize_document (the named next step).

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 precondition 'aus einem ausgestellten Angebot' tells the agent the source must be an issued quote, and 'Danach finalize_document' gives the correct follow-up call. No explicit exclusions (e.g. what to do for already-accepted or already-invoiced quotes), so not a full 5.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=false, and closed-world. The description adds meaningful state context—this creates a draft, not a finalized credit, and prices remain editable afterward—without contradicting 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 dense sentences front-load the resource and workflow; 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 three-parameter draft-creation tool with no output schema and safety annotations, the description supplies the critical nested-object mapping and follow-up workflow. The unexplained reason parameter leaves a small 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?

The nested quantities parameter is given precise semantics: keys are line-item IDs from get_document and values are returned quantities. The schema also documents id as Beleg-ID, but reason has no explanation in either place, so the low 33% coverage is only partly compensated.

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

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

The description identifies the resource as a credit note (partial credit) and the operation as creating a draft tied to an issued invoice. It is specific enough to separate this from a full-invoice cancellation, though it does not explicitly name cancel_invoice as the alternative.

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

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

It states the creation context (draft for an issued invoice) and prescribes follow-up actions: use update_document to adjust prices and finalize_document to issue. It lacks explicit guidance on when to choose this over cancel_invoice or other sibling tools.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the safety profile is covered. The description usefully reinforces the duplicate risk implied by non-idempotency, but never says what happens if a duplicate is still submitted (error vs. silent duplicate record) or whether the call is reversible.

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

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

Two short sentences with zero filler, and the dedup precondition is front-loaded right after the purpose statement. Nothing here is redundant with the title.

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

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

For a 14-parameter mutation with 21% schema coverage and no output schema, the description says nothing about which fields populate what, what the response contains (e.g. a new customer ID usable downstream), or duplicate handling. Adequate for the trigger, insufficient 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 only 21% across 14 parameters, yet the description mentions no field semantics at all — not that only `name` is required, not what `address_form` (sie/du), `buyer_reference` or `is_business` control. With low coverage the description should compensate and does not.

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 German verb+resource ("Neuen Kunden in der Kartei anlegen") that plainly distinguishes this from read-side siblings like get_customer and list_customers. It does not, however, draw any line against sibling write tools such as update_document or create_document.

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 the precondition for use: check with list_customers first for an existing customer. This names both the alternative tool and the condition that selects it, which is exactly the when/when-not guidance an agent needs.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=false, openWorld=false. The description adds real value beyond them by disclosing that no document number is assigned yet and that amounts are net EUR, but it says nothing about permissions, what the draft blocks or enables (send, PDF, e-invoice XML), or whether repeated calls duplicate records despite idempotentHint=false.

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

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

Two sentences, zero filler, with the draft/no-number constraint and the unit-of-currency rule front-loaded before the recipient guidance. Nothing repeats 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?

For a 25-parameter creation tool with no output schema, the essentials of what a draft is and how to identify the recipient are present, but the agent is left guessing about the returned identifier, whether a draft is editable, and how the tax/e-invoice parameters interact with the draft state.

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

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

With 25 parameters at only 32% schema description coverage, the description would need to carry a lot; it compensates for the highest-stakes decisions only — type (quote vs invoice), that amounts are net EUR, and the customer_id vs customer_name/address alternative. The remaining ~17 undocumented fields (payment terms, e_invoice_profile, service dates, buyer_reference) get no help in the description either.

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 ("Angebot oder Rechnung als Entwurf anlegen") plus a defining qualifier ("noch ohne Nummer") that separates a draft from a finalized document. An agent can distinguish this from finalize_document or update_document, though neither sibling is named explicitly.

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

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

Implies the when: use this to create a new draft rather than to edit or finalize one, and points at list_customers as the source of customer_id. But it never states that after creation you must call finalize_document, nor when to prefer update_document over re-creating, so the workflow context is only inferred.

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

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

Annotations already disclose that the tool is a non-readonly, idempotent, non-destructive mutation. The description adds the useful precondition that the quote must be issued, but it does not explain side effects of accepting or rejecting, nor what happens afterward.

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

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

The description is a single concise sentence with no wasted words, and the core action is front-loaded. It is appropriately brief, though the brevity contributes to missing usage and parameter 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 mutation tool with no output schema, the definition is under-specified. Annotations cover safety and idempotency, but the description does not explain decision effects, parameter semantics, or when to choose this tool over related 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 50%: id is described as 'Beleg-ID', but accepted has no description. The tool description does not compensate by explaining that true means accepted and false means rejected, nor what quote id format is expected.

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 action: record a customer decision on an issued quote. This is clear enough to distinguish from generic document updates, though it does not explicitly differentiate from siblings such as convert_quote_to_invoice or cancel_invoice.

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

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

There is no guidance on when to use this tool versus alternatives. It does not clarify whether this should be used before conversion, whether it is required for quote acceptance, or how it relates to convert_quote_to_invoice.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is carried structurally; the description adds the substantive constraint that only drafts are deletable and issued documents are not. It doesn't mention permissions or behavior when the id doesn't exist, so not 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 short sentences: the action first, then the exclusion and alternatives. Every clause earns its place, with no repetition of the title or schema.

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

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

For a single-parameter mutation with full annotation coverage and no output schema, the description covers purpose, scope, and correct alternatives. A note on not-found/idempotent behavior would make it fully 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?

Only one parameter with 100% schema description coverage ("Beleg-ID"), so the schema fully documents it. The description adds nothing about id format or lookup failure, which is acceptable at this coverage level but no better than baseline.

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

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

States a specific verb and resource ("Einen Entwurf löschen") and immediately scopes it against issued documents, which cannot be deleted. This lets an agent distinguish delete_draft from siblings like cancel_invoice without opening any schema.

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

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

Explicitly names the when-not condition ("Ausgestellte Belege lassen sich nicht löschen") and routes to the two correct alternatives, cancel_invoice and create_credit_note. No inference required.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful beyond-annotation behavior: the return is a base64-encoded file, and E-Rechnung PDFs include embedded XML. It does not mention error cases, permissions, or size limits.

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

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

Two short sentences, front-loaded with the action and resource, then the return-format detail. No redundant or wasted 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 single-parameter read/download tool with annotations and no output schema, the description covers the key return-format detail (base64) and the E-Rechnung XML nuance. The main missing piece is explicit routing to the sibling XML-download tool.

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

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

There is only one parameter ('id', Beleg-ID) and schema description coverage is 100%, so the schema already documents it fully. The description adds no additional meaning about the ID format or source, which is an acceptable baseline given complete schema coverage.

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

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

States a specific verb and resource ('PDF eines Belegs herunterladen') and adds the scope detail that E-Rechnung PDFs contain embedded XML. This implicitly distinguishes it from the sibling download_e_invoice_xml, though it never names that alternative directly.

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

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

The parenthetical about E-Rechnung with embedded XML hints at when this tool is appropriate, but it does not explicitly say when to use it versus download_e_invoice_xml or get_document. Usage is only implied, not 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=false, so the safety profile is covered. The description adds that retrieval is restricted to issued invoices and that the XML can be ZUGFeRD/Factur-X or XRechnung, which is useful context, but it omits what happens if the document has no e-invoice attached or whether the returned text is raw XML or transformed.

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

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

One short, front-loaded sentence with no filler. The trade-off is that it is a verbless noun phrase, so the key action has to be read off the tool name.

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

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

For a two-parameter read tool with no output schema, the description covers the resource and the return medium but leaves the enum parameter's effect and the failure case (no e-invoice present) unexplained. It is minimally viable rather than complete.

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

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

Schema coverage is only 50% and `profile` has no schema description beyond its enum. The description mentions both formats but never says that `profile` selects among them, nor what the default is when omitted — leaving a genuine ambiguity about whether the parameter filters or converts. It adds almost nothing beyond the schema.

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

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

The description names a specific resource (the e-invoice XML of an issued invoice) and enumerates the supported format families (ZUGFeRD/Factur-X, XRechnung), plus the returned medium ("als Text"). That differentiates it from the sibling download_document_pdf, though the verb itself only lives in the tool name.

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

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

There is no explicit when-to-use guidance: nothing tells the agent to prefer download_document_pdf for the PDF rendering, when an e-invoice actually exists, or when the `profile` argument should be supplied. The only usage signal is the implicit scope constraint "einer ausgestellten Rechnung", which the agent must infer.

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

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

The description adds important context beyond the annotations: finalization assigns a sequential number and makes the document permanently immutable. This reinforces the destructiveHint with concrete business meaning, though it does not mention permissions or edge cases such as finalizing a non-draft.

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

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

Two short sentences, front-loaded with the action and followed by the irreversible consequence. Every phrase contributes to understanding the operation, with no wasted 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?

The core destructive and irreversible behavior is clearly conveyed, which is especially important given destructiveHint=true. However, the description does not clarify the optional issue_date parameter or what state the referenced document must be in, leaving some gaps for a mutation tool with 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?

The description does not explain the two parameters. The schema documents 'id' only as 'Beleg-ID' and leaves 'issue_date' undocumented, so the 50% schema coverage gap is not compensated by the description.

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 action, issuing a draft, and its immediate consequence: a sequential number is assigned and the document becomes immutable. It distinguishes the operation from updatable or deletable drafts, though it does not explicitly name sibling alternatives such as cancel_invoice or update_document.

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 'Entwurf ausstellen', meaning it applies when a draft should become a finalized document. However, there is no explicit when-to-use guidance, no exclusions, and no direct comparison with siblings like send_document or update_document.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds value by naming what is returned (address, contact person, VAT ID) in the absence of an output schema, but it says nothing about behavior on a missing ID or any access constraints.

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

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

A single short sentence with zero padding, and the resource and returned fields are front-loaded. It is efficient, though it is terse enough that it omits useful context rather than being optimally structured.

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

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

For a one-parameter read tool whose annotations cover the safety profile, this is close to complete, and the description compensates for the missing output schema by naming the returned fields. The only real gap is undefined behavior when the customer does not exist.

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% — the single id parameter is documented as "Kunden-ID" — so the schema does the work. The description adds no syntax, format, or lookup semantics beyond what the schema already states, 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 pairs a specific verb ("lesen") with a specific resource ("Kunden") and the singular "Einen Kunden" signals single-record retrieval, which implicitly distinguishes it from the sibling list_customers. It never names that sibling or any alternative explicitly, so the differentiation is inferable 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: the singular article and the required id parameter suggest fetching one known customer. There is no explicit statement of when to use this versus list_customers, and no mention of prerequisites or error behavior for unknown IDs.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real value by naming the returned fields (Positionen, Status, offener Betrag, E-Rechnungs-Status), which matters since there is no output schema, but it says nothing about failure modes such as an unknown ID or access restrictions.

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

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

One short sentence with the verb and resource front-loaded and zero filler. Slightly clipped as a fragment, but every word earns its place.

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

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

For a single-parameter read tool with annotations covering safety and a description that lists the returned fields, an agent has what it needs to call it correctly. Only the absence of guidance on obtaining the ID or handling not-found cases keeps it from a 5.

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

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

Schema description coverage is 100% for the single 'id' parameter (Beleg-ID), so the schema already carries the semantics. The description adds nothing about the identifier's origin or format, which is the baseline-3 case.

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 (lesen) and resource (Beleg) and even enumerates what the read returns: line items, status, open amount, e-invoice status. That clearly separates it from list_documents or create_document, though no sibling is named explicitly.

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

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

The description gives no when-to-use guidance, no prerequisites, and no pointer to alternatives such as list_documents for discovering an ID. Usage is only inferable from the required 'id' parameter 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 destructiveHint=true, idempotentHint=false and non-read-only, so the safety profile is covered. The description adds real context beyond that: it generates a number (MA-…) and stores a PDF in the archive, telling the agent what side effects to expect. It stops short of stating permissions or whether prior notices can be revoked.

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 core action and condition, followed by the concrete outputs. Nothing is wasted.

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

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

With no output schema, the description carries return-value burden and does so adequately by noting the generated MA-… number and archived PDF. Combined with full param coverage and annotations, an agent has enough to call it correctly, though auth/irreversibility details are left implicit.

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

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

Schema coverage is 100%, so both id and level are documented in the schema (level empty = next level). The description reinforces the escalation concept but adds no syntax or format beyond what the schema provides, 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: issuing the next dunning level for an overdue invoice, including the escalation concept (Zahlungserinnerung, then Mahnungen). The action is unambiguous. No sibling happens to overlap, so no differentiation is needed, but it also doesn't explicitly route against 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 triggering context: use it for an overdue invoice to escalate to the next dunning level, and describes the progression order. There are no obvious alternatives among siblings to exclude, so the lack of explicit exclusions is minor.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior not in the schema: a fixed page size of 50 and the fact that the returned id is consumed downstream. It omits what an unqueried call returns and whether further pages exist beyond page 1.

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

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

Two short sentences with no filler; the searchable-field list comes first and the downstream id hand-off last. Every clause carries information an agent needs.

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

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

For a two-parameter, output-schema-less lookup tool the essentials are present: what can be searched, page size, and how the result is reused. But with zero required parameters, the description never says whether an empty query lists all customers or returns nothing, and it gives no sense of total counts or result limits.

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 0%, so the description must carry the parameters, and it does: the parenthetical maps q to the four searchable fields, and "50 je Seite" gives page its meaning. It stops short of stating whether page is 1-based or what the default page is.

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 ("durchsuchen") and resource ("Kundenkartei") and enumerates the searchable fields, so the operation is unambiguous. It does not, however, distinguish itself from the sibling get_customer, which an agent could equally reach for when looking up a customer.

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

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

Usage is implied by the field list and by the note that the returned id feeds create_document as customer_id, which hints at a lookup-then-create workflow. There is no explicit when-to-use statement, no mention of when get_customer is the better choice, and no guidance on calling with an empty q.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful behavior beyond annotations: results are newest first and paginated at 50 per page. It does not cover rate limits or authentication, but the annotation coverage lowers the burden.

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 very compact and front-loaded: the core action, ordering, pagination, and filtering are all covered in two short sentences with no waste.

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 annotations covering safety and no output schema to explain, the description gives enough context to invoke it correctly: ordering, page size, and both filter concepts. Pagination details and enum semantics are the main remaining gaps.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It clarifies that 'q' searches by customer or number and that 'type' filters by document type, but it does not explain page numbering/defaults, and it does not map enum values such as quote, invoice, credit_note, and cancellation to their meanings.

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: 'Belege auflisten' (list documents). It adds useful scope details such as newest-first ordering, page size, and filtering, making it clearly a list operation rather than a get/create/update operation. It stops short of explicitly naming a sibling tool to contrast with.

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

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

The description implies when to use the tool by explaining filtering by type and search term, but it does not explicitly state when to use this versus alternatives like get_document or list_customers. Usage guidance is present but mostly inferred.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent mutation. The description adds useful context that it only marks a document as sent rather than performing delivery, but it does not explain repeat-call behavior, permissions, reversibility, or what happens if the document is already marked sent.

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

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

The description is a single efficient sentence with the action and the usage condition front-loaded. Every part contributes information 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?

For a one-parameter mutation with annotations covering safety traits, the description supplies the essential usage context and clarifies that no actual sending occurs. Some edge-case behavior is unstated, but the core definition is complete enough to invoke 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% and the single "id" parameter is already documented as "Beleg-ID". The description adds no further parameter semantics beyond what the schema provides, which is acceptable for this simple case.

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 ("ausgestellten Beleg als versendet markieren") and clarifies that the document was sent by another route. It is clear what the tool does, though it does not explicitly name the sibling send_document as the contrasting operation.

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

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

It gives a clear condition for use: the issued document went to the customer via another channel such as personal email or post. It implies this is not the tool for sending from the system, but it does not explicitly name send_document as the alternative.

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

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

The description adds meaningful behavioral rules beyond the annotations: the amount is in euros, a negative amount means a reversal (Rückbuchung), and omitting paid_on defaults to today. It does not describe permissions or full side effects, but the annotations already cover read-only, idempotency, and destructiveness hints.

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

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

The description is two tight sentences with no wasted words. The key business rules are front-loaded and directly actionable.

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

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

For a non-idempotent mutation with four parameters and no output schema, the description covers the most important amount and date rules but omits note semantics, permission requirements, and any indication of what happens on success or failure.

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

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

With only 25% schema description coverage, the description must compensate. It usefully explains amount sign semantics and the paid_on default, but it leaves the note parameter undocumented and does not clarify what id refers to beyond the schema's ambiguous 'Beleg-ID'.

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: recording an incoming payment for an invoice. It is clearly distinguishable from most sibling tools, but it does not explicitly differentiate itself from close alternatives such as create_credit_note, which could also involve negative amounts.

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 implies the tool is for recording payments but gives no explicit guidance on when to use it versus alternatives like create_credit_note, cancel_invoice, or issue_dunning. There are no exclusions or prerequisite conditions 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 destructiveHint=true, openWorldHint=true and idempotentHint=false, so the agent knows this is an external, non-idempotent write. The description adds genuine value beyond that by explaining the mail routing: without own SMTP it goes via brandbill with the invoice e-mail as Reply-To, otherwise the sender account or default account. It still does not say whether the document is marked as sent afterwards, whether resending duplicates, or what happens on delivery failure.

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 the action front-loaded and the routing detail second. No filler. Slight density cost from the parenthetical, but 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 side-effecting tool with no output schema and no annotation detail beyond hints, the description covers the routing model but omits the observable outcome (does the document transition to 'sent'?) and any failure semantics. Adequate to invoke, not complete enough to predict consequences.

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

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

Schema coverage is only 17% (only 'id' is documented), so the description has to compensate. It does clarify the one non-obvious parameter indirectly: 'Absenderkonto bzw. Standardkonto' explains how mail_account_id behaves when omitted. The remaining parameters (to, cc, subject, body) are self-evident from their names and formats, but nothing is said about them in the description.

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 delivery channel and format: an issued document is sent as a PDF by e-mail. The qualifier 'Ausgestellten' also narrows scope to finalized documents, which is meaningful. It does not, however, distinguish this from the sibling mark_sent, which is the obvious confusion point for an agent.

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 'Ausgestellten' implies the precondition that the document must already be issued, which is implied rather than stated as a rule. There is no explicit when-not guidance and no mention of the alternative mark_sent for merely flagging a document as sent without sending mail. Usage is therefore inferable but not disambiguated.

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 idempotentHint=true, so the mutation and idempotency profile is covered. The description adds genuinely valuable behavior beyond that: patch semantics (only supplied fields change) and the critical warning that `lines` replaces all line items rather than merging. What it omits is what happens when the document is not a draft.

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

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

Two short sentences with no filler, and the partial-update rule plus the `lines` gotcha are front-loaded. Efficient, though arguably too terse given the tool's breadth.

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 25-parameter mutation tool with no output schema and low schema coverage, the description does far too little: it never states that the document must be a draft, never explains what is returned, and never covers interactions such as discount_percent vs per-line discounts or required-field implications when tax_regime changes.

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

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

With 25 parameters at only 36% schema description coverage, the description must compensate, and it only does so for `lines` (replace-all semantics). The many undocumented fields (customer_name, payment_terms_days, service_date, closing_text, etc.) receive no guidance, though most are self-explanatory by name.

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 ("Einen Entwurf ändern" = modify a draft), which is clearly distinct from create_document, delete_draft, and finalize_document. It does not explicitly name those siblings, but the draft scope 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?

The word "Entwurf" implies the tool applies only to drafts, which is a useful when-to-use signal, but it is never stated as a constraint nor contrasted with finalize_document or delete_draft. No prerequisites, no error conditions, no explicit alternatives.

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