Meistron

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

Beyond the annotations, it discloses key behavioral traits: nothing is sent to the customer, nothing is booked, the response reports which items were adopted and which header fields will be omitted, and invoice conversion is blocked. It also documents the two-step idempotency-key protocol, which neither the annotations nor the schema title convey.

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

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

The description is long but organized into thematic paragraphs, with the core limitation front-loaded and details grouped around order inheritance, header fields, and conversion. It is reasonably tight for an 11-parameter tool, though a few statements restate what the schema already explains.

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 tool with 11 parameters, nested objects, and no output schema, this is complete: it covers response behavior, ordering of data inheritance, configurable printing, side-effect boundaries, and retry semantics. An agent has enough contextual information to invoke it correctly and interpret the outcome.

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 documents each parameter. The top-level description adds cross-parameter meaning: default values drawn from the order, field precedence between belegkopf and belegkopf_aus_auftrag, the uniform tax-rate rule, and the idempotency-key flow. This is useful but incremental given how thorough the schema already 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?

The opening sentence states a specific action — 'Legt einen ANGEBOTS-Entwurf an' — and immediately distinguishes it from an invoice ('keine Rechnung', 'fordert kein Geld', 'wird nicht gebucht', 'Verschickt NICHTS'). This gives an agent a clear separation from sibling tools like rechnung_anlegen and auftrag_anlegen.

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 explains when to supply an order and what is inherited (material, times, subject, header fields), when to use own positions, and warns that conversion to invoice is not possible via this access. It does not explicitly name sibling tools as alternatives, but the quote-vs-invoice boundary is a usable selection criterion.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context beyond these by stating it shows which offers were already converted to invoices and which remain open, giving the agent a clear picture of the output without needing to infer.

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 sentences, front-loaded with the verb and resource, and every clause adds relevant information. 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?

As there is no output schema, the description carries the responsibility of explaining return values. It lists the fields (Nummer, Kunde, Betrag, Status) and the special conversion status, which covers the core information. It doesn't mention limits or ordering, but those are optional parameters in the schema.

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

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

Since schema description coverage is 100%, the baseline is 3. The description aligns with the 'nur_offen' parameter by mentioning open offers, but doesn't detail parameter syntax or add meaning beyond the schema. It mentions output fields rather than input parameters.

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

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

The description uses the specific verb 'Listet' (lists) and identifies the resource 'Angebote' with key fields (Nummer, Kunde, Betrag, Status). It clearly distinguishes from sibling tools like angebot_anlegen (create) and rechnungen_suchen (invoices) by focusing on offers and their conversion state.

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 clear context about what the tool returns (offers with conversion status), implying its use for checking which offers are converted or open. However, it does not explicitly name alternatives or state when not to use it, stopping short of full guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds useful behavior beyond that: default time-range behavior, suche including past records, customer scoping, and the returned fields. It does not mention pagination or ordering, but those are minor given the strong annotation coverage.

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 concise sentences put the primary purpose first, then refine behavior by input mode, then connect results to downstream tools. Every sentence earns its place and there is no redundant 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 read-only search/list tool, the description is largely complete: it states returned fields, default behavior, search modes, and how identifiers are used downstream. The lack of an output schema is compensated by listing result fields, though sorting and result-limit behavior are left to the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some context for behavior with and without a time range, but it mostly restates what the schema already says about suche and kunde_id. It does not substantially enrich parameter understanding 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 clearly states the operation: listing Aufträge over a period with specific result fields (Titel, Termin, Status, Ort, Kunde). It also differentiates this list/search tool from single-record siblings by noting that a result's Kennung is the input for auftrag_ansehen and rechnung_anlegen.

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

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

It gives clear usage context: no time range yields upcoming appointments, suche searches partial numbers/titles including past records, and kunde_id filters by customer. It does not explicitly state exclusions against sibling tools, but the downstream tool connection makes selection guidance clear enough.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses partial-update behavior, the exclusion of status changes, and a conditional side effect: assigned employees may receive a push notification on a real appointment shift, while the customer receives nothing. This is genuinely useful behavioral context not captured by annotations.

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

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

The description consists of two compact, information-dense sentences. The first front-loads purpose and scope; the second adds the side-effect warning. There is no filler and nothing repeats the annotations 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 mutation tool with no output schema and moderate schema coverage, the description sufficiently covers the key behavioral semantics (partial update, no status change, notification side effects). It reasonably relies on the schema for the date format and idempotency workflow. A minor gap is the lack of any mention of the return value or confirmation, but that is not critical given the annotations.

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

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

The schema covers 57% of parameters, and the description adds meaning by mapping 'Titel, Beschreibung, Ort oder Termin' to the relevant fields and explicitly stating that only supplied fields are touched. This partial-update semantics is not evident from the schema alone. The idempotency_key behavior is already thoroughly documented in the schema, so no duplication is needed.

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

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

The description uses the specific verb 'Ändert' (changes) and names the exact resource ('bestehenden Auftrags') plus the fields affected: Titel, Beschreibung, Ort, Termin. It also adds scoping constraints ('Nur die angegebenen Felder werden angefasst', 'Ändert NICHT den Status'), which clearly distinguishes it from create/view/search 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?

The first sentence clearly implies the tool is for modifying existing order fields, and the explicit 'Ändert NICHT den Status' provides a when-not boundary. However, it does not name alternative tools (e.g., auftrag_anlegen for status changes or new orders), so it stops short of full alternative routing.

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

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

Adds substantial behavioral context beyond the annotations: default assignment to the owner, notification behavior depending on an external setting whose default is off, and the guarantee that the response reports what was actually sent. It also clarifies side-effect boundaries (no invoice, no customer communication), with no contradiction with readOnlyHint=false, openWorldHint=true, or destructiveHint=false.

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

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

Four purposeful sentences arranged in order of importance: core action first, mandatory-person rule second, notification side-effect third, and negative scope last. No filler or repetition; the caps on 'JEDER', 'KEINE', and 'AUS' are effective emphasis.

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 create tool with no output schema, the description covers the essential behavioral rules, defaults, and side-effect exclusions, and even previews the response's key content. It leaves the exact response shape unspecified and does not restate the two-step idempotency protocol in the description, though that protocol is well documented in the schema, so a small gap remains.

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 documents all 8 parameters. The description mostly summarizes fields already visible in the schema and repeats the mitarbeiter default; the notification caveat adds context but is not parameter-level semantics, so the baseline 3 is appropriate.

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

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

States a specific action ('Legt einen neuen Auftrag an') and resource, lists core fields, and adds explicit negative boundaries ('Legt KEINE Rechnung an und schreibt dem Kunden nichts') that separate it from invoice- and communication-related siblings like rechnung_anlegen or rechnung_versenden.

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 indicates when to use it (creating a new order) and gives decision-relevant constraints: a responsible person is mandatory, owner is assigned by default, and notifications depend on the Betrieb's Aussenwirkung setting. It does not name alternative tools explicitly (e.g., auftrag_aendern or angebot_anlegen), so the routing is clear but not fully explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral detail beyond annotations: permission-dependent visibility ('sofern die Bereiche ... freigegeben sind'), limited contact data ('nur der Name'), cancellation-specific reason, and the exact scope of returned data.

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

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

The description is long, but every clause earns its place by specifying a distinct field or condition. The main field list is front-loaded, and the final sentence adds useful cross-tool context without redundancy. The structure makes a complex return payload easy to scan.

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?

Since there is no output schema, the description carries the full burden of explaining the return values — and it does so exhaustively: employee assignments, material billing status, un-invoiced hours, photo counts, cancellation reason, invoices, and net price. Permission caveats are also spelled out, so an agent knows what to expect under different access settings.

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 100% schema coverage and a single parameter described as 'Die Kennung des Auftrags,' the schema already documents the parameter adequately. The description does not add format, example, or lookup semantics beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb and resource — 'Zeigt einen einzelnen Auftrag ausführlich' — and enumerates exactly which fields are included. It also distinguishes itself from list-oriented siblings like 'auftraege_suchen' by emphasizing 'einzeln' and from 'rechnung_anlegen' by noting it is the pre-invoice view.

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

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

The description clearly identifies the intended context: 'Der übliche Blick, BEVOR aus dem Auftrag eine Rechnung entsteht.' It explains that material and hours shown here correspond to what 'rechnung_anlegen' would use, giving the agent a practical cue for when to choose this tool. However, it does not explicitly state when not to use it or compare it directly with other view/search 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 disclose readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds meaningful behavioral context beyond annotations by clarifying that the 'Summe der offenen Posten' is reported as RESTBETRAG with partial payments already deducted. It does not mention auth or rate limits, but for a simple read-only overview with zero parameters this is not a significant gap.

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

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

The description is two compact sentences. It front-loads the action ('Nennt die aktuellen Eckdaten'), lists the specific figures, uses a dash to clarify the RESTBETRAG nuance, and ends with a practical usage tip. Every sentence earns its place and there is no redundant content.

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

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

For a parameterless overview tool with no output schema, the description is remarkably complete. It specifies all included figures, interprets the meaning of one key metric, and provides guidance on when to call it. An agent can correctly invoke and interpret the result without additional documentation.

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 are zero parameters, so per the rubric the baseline is 4. The description does not need to explain any parameters; instead it focuses on output semantics, which is appropriate. No parameter-related information is missing.

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: 'Nennt die aktuellen Eckdaten' and enumerates the exact metrics (open orders, scheduled orders, unpaid/overdue invoices, sum of open items). It clearly distinguishes itself from search-oriented siblings like 'auftraege_suchen' and 'rechnungen_suchen' by offering a summary snapshot rather than a filtered list, reinforced by the phrase 'Guter erster Aufruf'.

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 a clear usage context: 'Guter erster Aufruf, um zu verstehen, worum es gerade geht' signals it is the initial orientation tool. It implies a 'when to use' scenario but does not explicitly name alternatives or state when not to use it (e.g., 'for detailed data use auftraege_suchen'). This is clear but not exhaustive.

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 discloses far more than the sparse annotations (all false hints): the request itself processes nothing, DATANORM uploads get auto-checked but prices are never applied, receipts are only stored, images can be attached to an order, the link requires a Meistron login to work, and files cannot be passed through chat as text or Base64 — with the rationale that character fidelity matters. These are exactly the behavioral traits that would otherwise cause an agent to promise the user the wrong outcome.

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 longer than average (four paragraphs), but every sentence earns its place: purpose first, then post-upload behavior, then the chat constraint with justification, then the direct action commands (show the link, require login, check with datei_stand). The rationale sentence about character loss is slightly verbose but helps an agent explain the constraint to a user. Front-loaded structure is excellent.

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 tool with 5 parameters, a two-phase idempotency protocol, and differentiated post-upload behavior, the description plus 100%-covered schema form a complete picture: the returned link is mentioned, the login prerequisite is stated, the follow-up tool is named, and per-file-type outcomes are specified. The behavior that only images appear in the order's photos is documented in both schema and description. No critical gap remains 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 the baseline of 3 applies. The schema already documents the zweck enum values, the lieferant_id requirement for datanorm (including the lieferanten_auflisten pointer), the two-phase idempotency_key protocol, and the gehoert_zu_auftrag caveat about no file view existing yet. The description's mention of 'Preisdateien von Lieferanten (DATANORM), PDFs, Belege und Fotos' reinforces the enum mapping but adds no new per-parameter meaning.

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

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

The first sentence states a specific verb+resource+outcome: 'Fordert eine Datei vom Menschen an und gibt einen Link zurück, über den er sie in Meistron hochlädt.' It lists the exact file types (DATANORM, PDFs, Belege, Fotos) and clearly differentiates from the sibling datei_stand by describing request-vs-check roles in one workflow.

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 clear context for when to use the tool (needing a file from a human, with the chat-upload path explicitly ruled out) and names datei_stand as the follow-up step. It also explains what the tool does NOT do — it does not apply prices or articles, which prevents misuse. It never explicitly names an alternative tool for a given condition, but the workflow and exclusions are concrete enough that an agent can route correctly.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints. The description goes beyond these by explaining the human processing delay and advising against frequent polling, which is important behavioral context not present in the structured metadata.

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

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

Two tightly written sentences: the first states the core purpose, the second provides usage timing and a critical warning. Every phrase earns its place, with no redundancy or fluff.

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

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

Despite having no parameters and no output schema, the description fully covers the tool's purpose, when to use it, and a key behavioral caveat. It gives enough context for an agent to know what to expect and how to interact appropriately.

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

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

The tool has zero parameters, so parameter-level explanation is unnecessary. The schema trivially covers all (non-existent) parameters, and the description provides no parameter details because none exist. Baseline 4 applies per guidelines for no-parameter tools.

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

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

The description clearly states the tool shows which files were requested and which have arrived, using the specific verb 'Zeigt' and resource 'Dateien'. It also distinguishes itself from the sibling tool 'datei_anfordern' by positioning itself as the post-request check, making its purpose unambiguous.

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

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

Explicitly instructs to use this tool after 'datei_anfordern' instead of guessing, and provides a clear exclusion: do not call repeatedly in short intervals because the human needs time. This gives strong when-to-use and when-not-to-use guidance, referencing the related 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?

Beyond the annotations, the description discloses a non-obvious global side effect: changes affect all future invoices and offers but not existing ones. It also states that certain fields remain unchangeable even with approval and gives a policy for out-of-scope requests. These are valuable behavioral details that annotations alone do not convey, and there is no contradiction with the annotations.

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

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

Three short, deliberately separated paragraphs: purpose and effect, immutable exclusions, and the viewing prerequisite. The content is front-loaded and every sentence carries operational weight, including the Meistron referral. The emphasis and list of exclusions are justified rather than 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 mutating settings tool, the description covers scope, immutability boundaries, handling of forbidden requests, and the necessary viewing pre-step. The idempotency protocol is already fully detailed in the input schema, so its absence from the description is not a gap. An agent has enough information to invoke the tool correctly.

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

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

Schema description coverage is 100%, and the schema already thoroughly documents feld, wert, and idempotency_key. The description does not add new parameter-level meaning beyond framing settings as company/invoice defaults and pointing to 'einstellungen_ansehen', which the schema already mentions. Baseline 3 is appropriate.

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

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

The opening sentence names the verb ('Ändert') and the resource ('Firmen- oder Rechnungsvorgabe'), then narrows the scope further: 'Wirkt auf ALLE künftigen Rechnungen und Angebote, nicht auf bestehende.' This clearly distinguishes the tool from 'einstellungen_ansehen' and gives an agent a precise mental model of what it does.

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

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

The description gives a concrete prerequisite and sequence: call 'einstellungen_ansehen' first to know today's value. It also defines when not to act by listing immutable fields and instructing agents to refer to Meistron for those requests. It stops short of framing this as an explicit 'use this instead of X' decision against an alternative tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds value beyond annotations by specifying what is intentionally excluded from the view (Bankverbindung, Steuernummern, Nummernkreise), giving the agent a clearer picture of the tool's limitations. No contradiction with annotations.

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

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

The description is two sentences long, front-loaded with the main purpose, followed by a practical use case and a concise list of exclusions. Every sentence adds meaningful information with no redundancy or fluff.

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

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

For a zero-parameter, read-only settings viewer, the description is complete: it explains what data is shown, what is intentionally omitted, and when it is useful. No output schema exists, but for this simple tool the description sufficiently conveys expected behavior.

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

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

The tool accepts zero parameters, and the input schema is empty. The description adds no parameter-specific details, as none are needed. The baseline for 0 params is 4, and the description does not need to compensate for any schema gaps.

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

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

The description clearly states the tool shows company data and settings for invoices and offers, naming specific elements (Zahlungsziel, Steuersatz, Stundensatz, Textbausteine). It also explicitly lists what is NOT shown (bank details, tax numbers, number ranges), which distinguishes it from related tools like einstellungen_aendern.

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 provides a clear use case: 'Nützlich, um zu erklären, warum eine Rechnung aussieht, wie sie aussieht.' This implies when to use the tool, though it does not explicitly mention alternatives or exclusion cases. The sibling tool einstellungen_aendern is not referenced, but the name and description make the view-vs-edit distinction obvious.

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 signal idempotency, but the description adds substantial behavioral detail: the exact duplicate-handling rule, no-op on multiple matches, server-assigned Kundennummer, and the conditional storage/use of contact data depending on explicit 'Vollzugriff und Vollautonomie' confirmation. No contradiction with 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?

The description is longer than average but dense and front-loaded: the core create action appears first, followed by necessary conditional behaviors. Every sentence contributes substantive guidance, though the second paragraph could be slightly tightened without losing meaning.

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

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

Given the tool's moderate complexity, no output schema, and rich idempotency semantics, the description is largely complete: it mentions the returned customer number, the duplicate-name branches, and the autonomy restrictions on contact data. The idempotency-key protocol is left to the schema, and there is no explicit guidance on what the agent should do when multiple same-named customers exist, so it is not a perfect 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 67%, and the description adds meaningful parameter-level semantics: it says name is sufficient, Firma and Anschrift are optional, and explains the autonomy constraint behind email/telefon/mobil. It does not individually describe ort/plz/strasse, but 'Anschrift' covers them collectively and the schema descriptions handle the remaining parameters 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?

The description opens with 'Legt einen neuen Kunden an', a specific verb and resource that clearly identifies creation as the core purpose. It goes further by disclosing the deduplication/upsert behavior and explicitly distinguishes this tool from search-oriented siblings like kunden_suchen.

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

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

It clearly states when to call the tool (creating a customer, with name being sufficient) and gives conditions: a single same-named customer updates instead of creating, while multiple same-named customers result in no change. It does not explicitly mention alternatives or exclusion criteria such as 'use kunden_suchen first', so it stops short of a 5.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses the concrete return shape and a deliberate limitation: it returns Kennung, Kundennummer, Name, Ort, and whether an email exists, but intentionally not contact data. It also explains why the address is not needed for sending. This is valuable behavioral context not available from the schema or annotations.

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

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

The description is front-loaded with the core purpose, followed by a crisp workflow warning and a focused explanation of output limitations. Each paragraph earns its place: no filler, but enough detail to prevent misuse.

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

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

For a read-only search tool with two optional parameters and no output schema, the description covers the search inputs, the returned fields, the key workflow prerequisite, and the intentional absence of contact details. An agent has everything it needs to select and invoke the tool correctly.

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

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

Schema description coverage is 100%: the `suche` parameter already explains partial name/company/location matching and the default listing of most recently created records, and `anzahl` already states default and limit. The description repeats the search criteria but adds no new parameter-specific information beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Findet Kunden des Betriebs nach Name, Firma oder Ort und nennt ihre Kennung.' It clearly states what the tool searches by and what it returns, and it distinguishes itself from the creation tool by emphasizing that this lookup supplies the Kennung needed by other tools.

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 guidance is explicit and emphatic: 'ZUERST SUCHEN, DANN ANLEGEN.' It directly warns against using `kunde_anlegen` without searching first, explaining the duplicate-customer consequence. This tells an agent exactly when to use this tool versus the sibling creation tool.

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

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

Annotations already cover read-only and non-destructive behavior. The description adds the limitation that this tool does not perform price import, which is valuable behavioral context. It also specifies the data returned (suppliers and last DATANORM price import).

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 primary function, and the exclusion is stated succinctly. 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 zero-parameter read-only tool, the description fully explains what it returns (suppliers and last price read dates) and what it doesn't do (import). No output schema needed given the simple nature.

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

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

The tool has no parameters, and the description correctly doesn't invent any. Baseline for zero parameters is 4, and there's nothing to deduct.

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

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

The description clearly states the tool lists suppliers and their last price import dates, with a specific verb ('Nennt') and resource. It also explains the purpose (answering whether catalog prices are current), which differentiates it from import-related tools.

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 NOT to use it (for price import) and directs to the alternative (uploading a file to Meistron). This provides clear usage boundaries and alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing the safety profile. The description adds useful context about the data fields shown (e.g., price, stock, location, and where stock comes from), but it doesn't disclose error handling, not-found behavior, or authorization requirements, which are not covered by annotations.

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

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

The description is a single, well-structured sentence that front-loads the action ('Zeigt') and resource ('Katalogartikel'), then lists the data scope. Every part contributes, with no filler or redundancy.

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

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

For a simple read-only view tool with one parameter and strong annotations, the description covers the key output fields (price, stock, location, stock movements). Without an output schema, it could be more explicit about the structure or extent of movements, but the description is largely sufficient for the tool's complexity.

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

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

The schema covers 100% of parameter descriptions: material_id is described as 'Die Kennung des Artikels.' The tool description adds no extra semantics beyond reinforcing that the tool views a catalog item by that identifier. Baseline 3 is appropriate given high 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?

The description uses the specific verb 'Zeigt' (shows) and clearly identifies the resource as a catalog article, listing the key data fields (price, stock, location, and stock movements). This distinguishes it from sibling tools like material_suchen (search) and material_buchen (book), providing a clear purpose.

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 the tool is for viewing a single material's details, but it doesn't provide explicit guidance on when to choose this over alternatives like material_suchen, nor does it mention prerequisites or exclusions. The usage context is only implied.

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

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

The annotations already mark destructiveHint=true and idempotentHint=false, and the description reinforces this with concrete operational context: every posting is permanently logged, cannot be deleted, and errors are corrected by a reversing posting rather than an undo. This goes beyond the generic annotation and is directly actionable for an agent.

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

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

Three sentences, each earning its place: the first explains the core operation and variants, the second adds the critical irreversibility/correction behavior, and the third routes to the correct alternative for a different case. The most important information is front-loaded and there is no fluff.

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 description covers the purpose, all three variants, the permanence/correction model, and the sibling alternative. The idempotency_key flow is fully described in the schema, so its absence from the description is not a gap. A minor gap is that the return/confirmation shape is not mentioned, but this is not a serious omission given how well the rest is 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%, and the schema already documents all five parameters in detail, including the subtle idempotency_key handshake. The tool description adds only a light interpretive layer for the movement types, not parameter-level semantics beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states a precise verb ('Bucht') and a clear resource ('Bestandsbewegung auf einem Katalogartikel'), then enumerates the three movement types: Zugang, Abgang and Inventur. It also distinguishes itself from material_zuweisen, so an agent can tell exactly what this tool does without opening the schema.

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

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

It gives explicit when-to-use guidance: this tool is for stock movements on a catalog item. It also names the sibling alternative and the condition that selects it: material that goes to an order should use material_zuweisen, because that links consumption with the order and makes it billable.

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 the tool read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds useful behavioral context: it returns price, unit, and stock, and explains the `nur_knapp` filter behavior. No contradictions with annotations.

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

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

The description is two sentences long, front-loads the core purpose, and adds a valuable use case in the second sentence. Every word earns its place; no fluff or redundancy.

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

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

Given the tool's moderate complexity (4 optional params, no output schema), the description covers the main behavior, key filter, and return fields. It doesn't detail pagination, but the schema documents `anzahl`. The description is adequate and well-contextualized within its sibling set.

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

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

The input schema provides 100% coverage with meaningful descriptions for all 4 parameters. The description's mention of `nur_knapp` reinforces the schema but doesn't add new semantic detail beyond it. Baseline 3 is appropriate since 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 uses a specific verb ('Durchsucht') and resource ('Materialkatalog'), and clearly states the search criteria (Bezeichnung/Artikelnummer) and output fields (Preis, Einheit, Lagerbestand). This distinguishes it from sibling tools like material_ansehen (view single) and material_buchen (booking), making the purpose 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 description gives a concrete usage scenario: with `nur_knapp` it lists items below minimum stock, described as 'der übliche Einstieg vor einer Bestellung' (the usual entry point before an order). While it doesn't explicitly name alternatives or exclusions, the context is clear enough for an agent to know when to choose this search tool.

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

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

Goes well beyond the annotations: it discloses the immediate stock deduction side effect, the failure mode for insufficient stock (rejected rather than booked into negative), and the downstream invoicing consequence. All disclosures are consistent with destructiveHint=true and readOnlyHint=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?

Four sentences, each earning its place: core purpose, side effect and downstream consequence, failure mode, and scope boundary. The primary action is front-loaded in the first sentence with zero filler.

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

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

Covers side effects, failure behavior, and scope boundary, with the idempotency protocol fully documented in the schema. The only notable gap is the success response shape — there is no output schema and the description does not say what the caller receives on success.

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%; every parameter has a meaningful description, including an exceptionally detailed two-phase protocol for idempotency_key. The tool description itself adds only marginal parameter context (e.g., stock availability constrains menge), so the baseline 3 applies since the schema does the heavy lifting.

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

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

States a specific verb and resource: 'Bucht Material oder Werkzeug auf einen Auftrag' (books material or tool onto an order), which is immediately distinguishable from pure stock tools and general order tools. The closing 'Legt KEINE Rechnung an' explicitly draws the boundary against invoice creation, so an agent can tell it apart from rechnung_anlegen.

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 intended context — consumption is assigned to the order so it can later be carried into an invoice — and explicitly states what it does NOT do ('Legt KEINE Rechnung an'). However, it never names sibling alternatives such as material_buchen or rechnung_anlegen directly, so routing between siblings is implied rather than explicit.

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, idempotentHint, and openWorldHint. The description adds context about what is listed (people assignable to orders) and the output fields (name and ID), which is useful. However, no further behavioral traits (e.g., pagination) are disclosed, but given the simple nature and annotation coverage, this is adequate.

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 sentences: the first states the tool's function, the second provides usage guidance. It is concise and front-loaded.

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 listing tool with zero parameters and no output schema, the description covers the essential context: what it returns, when to use it, and the annotations cover safety. No additional information seems necessary.

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

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

The tool takes no parameters. With zero parameters, the baseline is 4; the description doesn't need to compensate and does not add parameter-specific details.

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

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

The description uses the specific verb 'nennt' (lists), specifies the resource 'Personen, denen ein Auftrag zugewiesen werden kann' (people assignable to an order), and notes the output includes name and identifier. This clearly distinguishes it from sibling tools like 'lieferanten_auflisten'.

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 instruction 'Vor dem Anlegen eines Auftrags aufrufen, wenn nicht klar ist, wer zuständig sein soll' explicitly states when to use the tool (before creating an order when responsibility is unclear). This provides clear context and timing.

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 annotations: explains that the draft has no Rechnungsnummer until sending, that copying from an Auftrag is conditional on settings, that printed Belegkopf fields depend on company settings, and that mixed tax rates are rejected at finalization. This is rich, non-obvious behavioral disclosure.

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?

Long but information-dense; each paragraph and sentence contributes a distinct behavior or constraint. Purpose is front-loaded first, followed by order-copying semantics, then Belegkopf details. No filler or repetition of schema content.

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

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

For a complex 11-parameter nested tool with no output schema, the description covers the full workflow: draft creation, number assignment, order inheritance, settings dependencies, tax behavior, and response hints. It gives an agent enough to use the tool correctly in autonomous operation.

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

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

Schema coverage is 100%, but the description adds real semantic value: defaults for betreff, kunde_id and belegkopf; precedence of belegkopf_aus_auftrag; the effect of ohne_material/ohne_zeiten; and the whole-Beleg Steuersatz rule. It describes parameter interactions and business rules, not just field names.

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 clearly: 'Legt einen Rechnungs-ENTWURF an' — a specific verb and resource, and explicitly a draft, not a final invoice. It also says 'Verschickt NICHTS an den Kunden', which distinguishes it from rechnung_versenden.

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 context: describes the usual path via an Auftrag, when own positions should be added, and that no customer dispatch happens. It does not explicitly name exclusions such as 'use angebot_anlegen for quotes', so it lacks full alternative routing.

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 mark it read-only, idempotent, and non-destructive; the description goes further by disclosing exactly what is returned: header data, line items, totals, tax, discounts, payment status, dunning level, pause, original PDF flag, cancellation reason, project, and order. This is rich behavioral context beyond the structured annotations and is especially valuable because there is no output 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?

The description is front-loaded with the core action and then uses a structured list of invoice elements, each earning its place by clarifying what will be returned. The closing sentence adds a meaningful usage contrast without redundancy.

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

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

Given a single required parameter, full schema description coverage, and safety annotations, the description is complete for the agent's invocation and expectation-setting. It enumerates the return contents thoroughly, compensating for the absence of an output schema, and no critical calling context is missing.

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

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

Schema coverage is 100% and the one parameter, rechnung_id, is already described as 'Die Kennung der Rechnung.' The description adds no additional meaning about the parameter's format or semantics, so the baseline score of 3 is appropriate.

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

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

The description opens with the verb 'Zeigt' and a specific resource, 'eine einzelne Rechnung vollständig', immediately establishing the tool's purpose. The long enumeration of fields makes it unmistakably a detail-view tool and distinguishes it from sibling tools like rechnungen_suchen or rechnung_versenden.

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

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

The description clearly implies the tool is for full inspection of one invoice ('einzelne Rechnung vollständig') and adds the purpose statement 'prüfen, WAS auf der Rechnung steht — nicht nur, wie viel.' It does not explicitly name alternatives or exclusions, but the context is unambiguous enough for an agent to select it over search or mutation 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 read-only, idempotent, non-destructive behavior. The description goes beyond these by explaining partial payment display (Rest neben Betrag, Zeile als teilbezahlt), the sorting behavior for `nur_offen` (by age of overdue), and critical handling of UUIDs (never ask humans to input/repeat them). These are concrete behavioral traits not present in annotations.

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

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

The description is informative but slightly verbose. It front-loads the output fields and then explains partial payments, the `nur_offen` use case, the `suche` behavior, and the UUID rule. Each sentence earns its place, but the UUID guidance could be more tersely phrased. Still, it is well-structured and not bloated.

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

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

Given the annotations (read-only, non-destructive, idempotent) and complete schema coverage, the description covers all essential aspects: what fields are returned, the behavior of filters (nur_offen, suche), sorting, and the critical UUID handling. It also implies how results feed into `rechnung_ansehen`. No missing information for an agent to call it correctly.

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

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

Schema description coverage is 100%, so all six parameters have descriptions. The tool description adds extra meaning for `nur_offen` (unpaid, sorted by overdue age) and `suche` (finds paid/cancelled/drafts), enriching the agent's understanding beyond the schema's basic descriptions. It does not address `von`, `bis`, `anzahl`, or `nur_ueberfaellig` in the description, but these are adequately covered by the schema, so the added value is sufficient.

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

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

The description clearly states it lists invoices with key fields (number, customer, amount, status, due date, outstanding balance) and differentiates from siblings like `rechnung_ansehen` (view specific) and `rechnung_anlegen` (create). It also names follow-up tool `rechnung_ansehen` for found IDs. The verb 'Listet' is specific and the resource is unambiguous.

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

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

It provides contextual usage: 'der übliche Einstieg für offene Posten' and explains the `suche` parameter as a way to find specific invoices including paid, cancelled, and drafts. It also advises using internal identifiers only for follow-up tools. However, it does not explicitly contrast with other search siblings (e.g., `auftraege_suchen`, `kunden_suchen`) or list conditions when this tool is not appropriate, leaving some inference to the agent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value beyond that by guaranteeing 'versendet NIEMALS etwas' and 'verändert KEINE Daten — auch dann nicht, wenn Vollautonomie aktiv ist', which covers autonomous execution edge cases. It also discloses a short-lived protected draft PDF, a behavioral trait not present in the annotations. No contradiction.

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

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

The description is dense but every sentence earns its place: core purpose, inspection scope, negative guarantees, usage triggers, and input workflow. It is front-loaded with the read-only guarantee, then progressively adds details. The length is justified by the need to prevent accidental sends and to state safety guarantees explicitly.

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 tool with a single required parameter, no output schema, and rich annotations, the description covers the full call precondition, the complete inspection scope, and the safety profile. An agent can correctly select and invoke this tool without missing critical context. The only minor omission is exact return format, but that is not required given 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 description coverage is 100%, so the schema already fully documents rechnung_id as the internal ID from rechnungen_suchen, to be passed between tools and never typed by the human. The description repeats this same guidance without adding new semantic details such as format or examples. Since the schema carries the burden, baseline 3 is appropriate.

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

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

The description opens with a specific verb ('Prüft garantiert nur lesend') and a concrete resource ('den vollständigen Rechnungsentwurf vor dem E-Mail-Versand'), enumerating all inspected fields. It explicitly differentiates itself from siblings by listing what it never does (send, assign invoice number, freeze PDF, create release) and points to rechnungen_suchen for ID resolution. This clearly distinguishes it from rechnung_versenden and rechnung_ansehen.

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 explicit trigger phrases ('zeig mir die Versandvorschau', 'welcher Absender wird benutzt?', 'prüfe vor dem Versand') and mandates this tool for those queries. It also supplies an explicit workflow precondition: resolve rechnung_id via rechnungen_suchen and never ask the human for the UUID. This is strong when-to-use guidance with alternatives implicitly excluded.

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?

No contradiction with annotations (destructiveHint=true, readOnlyHint=false). The description far exceeds the annotation burden: it discloses that sending makes the invoice GoBD-immutable, that an email cannot be recalled, the two-phase behavior where the first call sends nothing out, the server-controlled autonomous mode the model cannot enable, sender fallback rules, and address-verification constraints. This is rich behavioral context beyond the structured fields.

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

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

Front-loaded with purpose and the critical sibling rule, followed by a clear numbered two-step flow and then mode-specific rules. It is long, but the length is earned by the irreversibility of sending invoices to real customers; some safety points (address verification, email non-retrievability) are repeated in different forms, which is defensible for a destructive tool but keeps it from a perfect score.

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?

Has no output schema, yet the description specifies what the first (preview) call returns — alle Positionen und Summen, Empfänger, Mailtext, Standard-Absender, Antwortadresse, Anhangsliste, geschütztes Entwurfs-PDF and the Freigabewort. With four parameters, two operating modes, an idempotency protocol, and server-side defaults, nothing an agent needs to call this tool 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% and each parameter is already richly described (source via `rechnungen_suchen`, status 'Entwurf', release-word format, idempotency pattern). Above that baseline, the description adds workflow-level meaning: it ties `freigabe` to the two-step call sequence, `idempotency_key` to the fully autonomous mode, and clarifies which parameters apply in which operating mode.

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: 'Versendet einen Rechnungs-Entwurf per E-Mail an den Kunden' (sends an invoice draft by email), and immediately distinguishes itself from the sibling `rechnung_versand_vorschau` by scope: actual sending vs. pure review. The irreversible consequences (Rechnungsnummer vergeben, PDF eingefroren, GoBD-unveränderlich) further pin down what this tool uniquely does.

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

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

Explicit when/when-not guidance: 'Nur für den tatsächlichen Versand verwenden. Für eine bloße Prüfung ohne Datenänderung immer `rechnung_versand_vorschau` aufrufen.' It also excludes letters outright ('BRIEFE GEHEN ÜBER DIESEN ZUGANG NICHT') and routes them to Meistron, and encodes a mandatory two-step call pattern (preview without `freigabe`, then send with `freigabe`).

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

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

Annotations already declare readOnly and idempotent hints, so the description need not repeat safety. It adds the default ordering (due soonest first) and the returned fields, which is useful but not extensive. There is no mention of pagination or limits beyond the schema.

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

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

The description is concise: one sentence stating the purpose, one for default behavior, and one for a typical use case. It front-loads the core action and avoids superfluous 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?

Given the rich annotations (readOnly, idempotent, non-destructive) and full schema coverage, the description provides sufficient context. It states the output fields and a practical use case, making it complete for a search tool without needing to explain return formats.

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

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

The schema covers all parameters with descriptions (100% coverage), so the description adds no extra parameter semantics. The mention of output fields is helpful but not about parameters. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists maintenance contracts with specific fields (customer, system, rhythm, next due date), distinguishing it from sibling search tools like order or invoice searches. It also mentions default behavior for no arguments, making the purpose 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 description provides a concrete use case ("welche Wartungen stehen im nächsten Monat an?") and explains default behavior, but it does not explicitly contrast with alternatives like wartungsvertrag_ansehen or other search tools. Still, the context is clear enough for appropriate selection.

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

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

Die Beschreibung offenbart wesentliche Seiteneffekte: Änderungen ziehen in noch nicht begonnene Wartungsaufträge nach, während laufende und abgeschlossene unberührt bleiben. Sie stellt zudem klar, dass es sich um eine partielle Aktualisierung handelt („Nur die angegebenen Felder werden geändert“). Das geht deutlich über die Annotationen hinaus.

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?

Drei Sätze ohne Redundanz: Der erste benennt Aktion und Felder, der zweite die Seiteneffekte, der dritte die partielle Update-Logik. Jeder Satz trägt zur korrekten Nutzung bei.

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?

Für ein komplexes Werkzeug mit 18 Parametern sind die Querschnittsregeln (Nachziehen in Aufträge, Partial-Update, Pause/Ende-Verhalten) gut abgedeckt. Ein Hinweis auf das Rückgabeformat oder die Notwendigkeit einer bestehenden Vertrags-ID wäre noch hilfreich, ist aber durch Schema und Kontext teilweise abgedeckt.

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?

Die Schema-Abdeckung ist mit 100 % bereits sehr hoch, daher liegt die Basis bei 3. Die Beschreibung fügt mit „Nur die angegebenen Felder werden geändert“ eine übergreifende Semantik hinzu, die für alle Parameter gilt und im Schema so nicht explizit steht.

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?

Die Beschreibung nennt ein spezifisches Verb („Ändert einen Wartungsvertrag“) und listet die betroffenen Felder sowie die Sonderfälle Pause/Beenden auf. Sie grenzt das Werkzeug klar von den Geschwistern wartungsvertrag_anlegen, wartungsvertrag_ansehen und wartungsvertraege_suchen ab.

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?

Der Verwendungszweck ist eindeutig: Änderung eines bestehenden Wartungsvertrags. Es fehlen jedoch explizite Ausschlusskriterien oder Verweise auf Alternativen (z. B. „zum Anlegen nutze wartungsvertrag_anlegen“), was den Score knapp unter die Bestbewertung drückt.

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

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

With annotations being minimal (all false hints, no safety profile), the description carries the behavioral disclosure burden and succeeds. It reveals that the contract number is assigned by Meistron (so the agent should not expect to supply one), that the due date must be in the future (validation boundary), and — critically for a write operation — the side-effect limits: no order is created (it emerges automatically later) and no customer notification is sent (reminders go only to the company). This prevents the agent from assuming hidden downstream effects.

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 four short sentences with zero filler; each sentence earns its place and the main purpose plus mandatory fields are front-loaded. The negative side-effect disclosures are appropriately emphasized with capitalization ('KEINEN Auftrag', 'NICHTS'), though placing these caveats before the contract-number detail would have made the structure slightly stronger.

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 15-parameter creation tool with no output schema and no meaningful annotations, the description covers the essential decision-relevant behavior: required fields, date validation, numbering responsibility, and side-effect boundaries. The only gap is that it never indicates what the call returns (contract ID, success confirmation, the idempotency key flow hinted at in the schema), which matters more because there is no output schema to document it.

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

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

Schema description coverage is 100%, so the baseline is 3 and the description need not repeat parameter details. It adds modest value beyond the schema by explaining that the contract number is generated by Meistron (clarifying an absent parameter/capability) and reinforcing which three fields are mandatory, but most of the parameter-level meaning lives in the schema descriptions already.

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

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

The description opens with a specific verb and resource: 'Legt einen wiederkehrenden Wartungsvertrag an' — creating a recurring maintenance contract. It also distinguishes itself from siblings by explicitly disclaiming what it is not: it creates no order (differentiating from auftrag_anlegen) and sends no notifications (differentiating from rechnung_versenden). The 'wiederkehrend' qualifier separates it from one-off contract or order tools.

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 clear usage context: it names the mandatory inputs (Kunde, Rhythmus, erste Fälligkeit, matching the schema's required fields) and states the date must be in the future. It gives exclusionary guidance by stating it creates no order and sends nothing, helping an agent decide whether this tool fits the goal — though it never names an alternative tool explicitly for when an order or customer communication is actually wanted.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral context by specifying exactly what fields are returned and noting that it includes orders that have already arisen from the contract, which is not evident from annotations alone. No contradictions with annotations.

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

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

The description is a single well-structured sentence that front-loads the action ('Zeigt') and uses a colon to efficiently list the included details. Every element earns its place, with no redundancy or filler.

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

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

Given the tool's low complexity (one required parameter, no output schema), the description is reasonably complete: it enumerates the key fields returned and alerts the user that generated orders are included. It does not describe the return format or error behavior, but these are less critical for a simple read-only view, so the minor gap is acceptable.

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 input schema has 100% coverage: vertrag_id is described as 'Die Kennung des Wartungsvertrags.' The tool description does not add further semantic detail about the parameter, but with full schema coverage the baseline of 3 is appropriate—the schema already handles the semantic burden.

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

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

The description clearly states it shows ('Zeigt') a maintenance contract in detail and enumerates specific fields (Rhythmus, nächste Fälligkeit, Objektanschrift, Anlage, Zuständige, Erinnerungsstufen) plus derived orders. This verb+resource structure distinguishes it from sibling tools like wartungsvertraege_suchen (search) and wartungsvertrag_aendern (edit).

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

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

The description implies usage—when you need full details of a single contract, this is the view tool—but it does not explicitly state when to use this tool versus alternatives like wartungsvertraege_suchen. No exclusions or alternative names are mentioned, relying on the tool name and context to convey positioning.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds behavioral nuance by noting that days with missing clock-out are also listed and do not count, which goes beyond structured metadata.

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 sentences: the first states the core purpose and output, the second adds an important caveat about missing clock-outs. No filler words, and the key information is front-loaded.

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 description covers the input (period), the output (per-employee sums, day counts, missing clock-out days), and a data quality note. It does not describe sort order or exact JSON structure, but given the absence of an output schema and the tool's simplicity, this is nearly 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?

Both parameters 'von' and 'bis' are fully described in the schema with date format descriptions. The tool description only references 'eines Zeitraums', confirming the period but adding no extra semantics. With 100% schema coverage, a baseline of 3 is appropriate.

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

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

The description uses the specific verb 'Fasst zusammen' with the resource 'erfassten Arbeitszeiten eines Zeitraums' and details the output per employee. It clearly distinguishes from sibling tools like 'mitarbeiter_auflisten' by focusing on summarizing time records.

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

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

The description implies usage when a summary of working hours for a period is needed, giving clear context. It does not explicitly state exclusions or alternatives, but no direct sibling for this task exists among the listed tools, so the implied guidance is sufficient.

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