FrankKi

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

The annotations already declare readOnlyHint=true and destructiveHint=false, and the description's 'listet' is consistent with that, so there is no contradiction. The description adds the partner address-book scope and optional filtering as context, but it does not disclose pagination behavior, result format, or other side effects beyond what annotations establish.

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 short and front-loads the core action, but it repeats the same content in German and English, creating redundancy. The bilingual duplication may be intentional, but it prevents the description from being maximally concise.

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

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

For a simple read-only list tool, the description covers the resource and search filters, and annotations cover the safety profile. It still leaves limit and reasoning undocumented and provides no guidance on when to choose address_search_company instead, so it is adequate but not fully complete.

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

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

Schema description coverage is 0%, so the description must compensate by explaining parameter meaning. It clarifies that searchQuery can filter by name, city, or client, but it leaves limit and reasoning undocumented, making those parameters ambiguous for an agent.

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) with the resource being 'addresses in the partner address book' and states optional filters by name, city, or client. It clearly conveys the operation, though it does not explicitly contrast it with the sibling address_search_company, so it stops short of full sibling differentiation.

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

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

The description explains that the tool lists addresses and may optionally be filtered, implying a read/listing scenario. However, it gives no explicit when-to-use guidance, no exclusions, and does not mention alternative tools such as address_search_company or address_upsert.

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 operation read-only and non-destructive, and the description aligns with that by using 'Sucht' and 'liefert' rather than mutation verbs. It adds useful context about the directory scope and the authority PO box, but it does not disclose behavior for no matches, multiple matches, or malformed queries.

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 short and front-loaded with the core purpose, and the bilingual German/English pair makes it broadly readable. The English translation duplicates the German sentence exactly, adding length without new information, which 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?

With no output schema and no parameter documentation, the description is the only source of behavioral and semantic context. It covers the return value in general terms but leaves the country/reasoning parameters undefined and gives no guidance on result ambiguity or edge cases, so an agent cannot fully predict the tool's 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 input schema has no parameter descriptions (0% coverage), so the tool description must clarify parameters. It clarifies that the search targets company/authority names and makes query semantics inferable, but it does not explain the optional country parameter or the reasoning parameter at all.

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

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

The description names a specific action and resource: searching companies and public authorities in a directory and returning the matching mailing address, including authority PO boxes. This clearly differentiates the tool from sibling address tools like address_validate (validation) and address_list (listing).

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 should be used when an agent needs a directory lookup for a company or authority mailing address. However, it does not state when to prefer an alternative, such as address_validate for validation or address_list for browsing, nor does it mention any exclusions.

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

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

Annotations already establish readOnlyHint=false and destructiveHint=false, so the mutation profile is known. The description adds the useful behavioral fact that the address is validated using country-specific rules. However, it does not disclose upsert semantics, such as whether addressId selects an existing record for update, what happens on validation failure, or whether omitted fields are preserved or overwritten.

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

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

Two compact sentences, in German and English, front-load the operation and validation behavior without extraneous detail. The bilingual duplication is justified in a German-context tool and every sentence contributes 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?

For a 12-parameter upsert with no output schema, the description is too thin. It omits create-vs-update selection, country defaulting, validation failure behavior, and any explanation of the listed address attributes. An agent would need to infer or probe the tool to call it correctly in non-trivial cases.

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

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

Schema description coverage is only 8%, so the description needed to carry most parameter meaning, but it does not. It only broadly implies that fields like name, street, and city are address-book attributes and that country matters for validation. It fails to explain the create-vs-update role of addressId, the meaning of isDefault, addressType, mandantennummer, or behavior around required fields.

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

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

The description states a specific action: 'Creates or updates an address in the partner address book' and adds a distinct behavior, country-specific validation. This clearly separates it from read-only siblings like address_list and address_search_company, and from address_validate, whose exclusive purpose is validation. The bilingual text reinforces the intended resource and operation.

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

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

The description makes the usage context clear: call this tool when an address needs to be created or updated in the partner address book. It does not explicitly name alternatives or state when not to use it, such as directing validation-only needs to address_validate. Thus it provides clear context but no exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds valuable behavioral context beyond that: 'the address book is left untouched', 'country-specific rules', and the specific failure result 'ADDRESS_INVALID'. The only minor gap is no mention of success return values or soft-warning behavior, so it's not a full 5.

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

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

The description is compact and front-loaded: first sentence states purpose and result, second sentence clarifies non-mutation and routes to the alternative. The bilingual version is not wasteful; every sentence carries meaningful guidance.

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 purpose, read-only behavior, and the hard-failure result, and it identifies the correct sibling for mutations. However, with 12 parameters and no output schema, it omits what a successful validation returns, how soft failures are handled, and any input-format expectations. This is adequate but has clear gaps.

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

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

Schema description coverage is only 8% (only 'country' is documented), and the description does not compensate. It does not explain the meaning or expected format of name, street, city, zip, houseNumber, or other parameters, nor how they relate to the validation logic beyond the generic 'address' context. This leaves the agent to infer parameter semantics from the schema alone.

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

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

The description states a specific verb and resource ('validates an address using country-specific rules') and a concrete outcome ('reports hard failures as ADDRESS_INVALID'). It also explicitly distinguishes itself from address_upsert by naming it as the tool for creating or changing an address, so an agent can tell them apart immediately.

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 usage guidance: it is 'a check only' and should not be used for mutation, and it directly names the alternative tool (address_upsert) for creating or changing an address. This leaves no ambiguity about when to choose this tool over its sibling.

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

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

With readOnlyHint=true and destructiveHint=false, annotations already cover the safety profile. The description adds useful behavioral context beyond that: results are aggregated rather than raw records, and monetary amounts are net costs in euro-cents, which matters for interpreting the 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 front-loaded with the core purpose and uses a short, useful second sentence for the unit clarification. The bilingual DE/EN repetition is intentional in this schema family, but it is the only slight redundancy; otherwise the text is appropriately sized.

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 analytics tool with six optional parameters and no output schema, the description covers all returned metric categories and the critical net-cents unit. Defaults and ranges are handled by the schema. The main gap is that the 'reasoning' parameter is left unexplained in both the description and 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 coverage is high at 83%, so the schema already documents most parameter meaning. The description adds some business context for metric values like 'Kosten pro Mandant zur Weiterberechnung' and 'Ausgaben gegen die gesetzten Limits', but it does not clarify the undocumented 'reasoning' parameter or add syntax-level detail.

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

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

The description opens with the specific verb 'Liefert' and the resource 'aggregierten Kennzahlen des Partnerkontos', then enumerates the concrete metric groups returned. It is clear and not a tautology, but it never contrasts itself with sibling tools, so sibling differentiation is implied rather than explicit.

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

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

The description makes it implicitly clear that the tool is for partner-account aggregated analytics, which helps an agent select it for KPI requests. However, it does not state explicit when-to-use or when-not-to-use conditions, nor does it name alternative tools such as letter_list or order_status.

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 (destructiveHint=true, readOnlyHint=false) already flag mutation and destructiveness, and the description goes well beyond them: it discloses the 10-minute grace window before dispatch, the ability to cancel via order_cancel, that rejection keeps the letter as a draft, and that the reservation is refunded. These consequences are not derivable from annotations and are exactly what an agent needs before a destructive decision.

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?

Each language block (DE/EN) is well-structured — purpose, mandatory precondition, timing, then rejection consequences — with critical constraints front-loaded via WICHTIG/IMPORTANT. But the description fully duplicates every sentence in both languages, roughly doubling its length; for any single reader, half the sentences are redundant, which prevents a higher 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?

For a complex, destructive tool with 6 parameters and no output schema, the description covers the decision-critical ground: preconditions, consent flag, dispatch timing, cancellation path, and rejection side effects. The remaining gaps — return format, error behavior for already-decided or non-pending approvals, and the purpose of clientOrderId — are secondary but real, since no output schema exists to cover them.

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

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

Schema description coverage is only 17%, so the description must compensate. It does explain user_saw_preview (when it must be true) and decision (approve dispatches after 10 minutes; reject preserves draft and refunds). However, comment, reasoning, and clientOrderId receive no semantics in either schema or description, and it is unclear whether reasoning is expected on rejection. Compensation is partial, not complete.

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+resource pair — 'Approves or rejects a pending approval on the human's behalf' — making the tool's function unambiguous. The 'on the human's behalf' framing distinguishes it from siblings like approval_submit (creating a request) and approval_list/approval_status_app (read-only views), and from approval_decide_app, which presumably runs an interactive flow for the human to decide.

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?

Provides an explicit, imperative precondition: before calling 'approve', the agent MUST show the preview link, exact price, and delivery type and obtain consent, then set user_saw_preview:true. It also names the concrete alternative (order_cancel) to invoke if the human says 'stop' within the 10-minute window, giving the agent both when-to-call and when-not-to-call 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?

Beyond the annotations, the description discloses a non-obvious delayed side effect: on approval, the letter is sent only after 10 minutes and can be stopped during that window. It also emphasizes a human-in-the-loop prerequisite, which is valuable behavioral context for an agent deciding whether to call the tool.

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

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

The description is short and front-loaded, repeating the key constraint first. However, the German and English versions duplicate the same content almost entirely, so each sentence does not earn its place for an English-reading agent.

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

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

With four undocumented parameters and no output schema, the description is too sparse for reliable invocation. It covers the high-level purpose and delay behavior, but leaves cardNonce, reasoning, and any stop/cancel mechanism unaddressed.

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

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

Schema description coverage is 0%, and the description does not explain key parameters such as cardNonce or reasoning, nor does it clarify when reasoning is required or what cardNonce represents. The action words map only loosely to decision and approvalId.

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

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

The description names a specific action ('approves or rejects the displayed approval'), a specific resource ('Freigabe-Karte' / approval card), and a clear trigger ('after the human pressed the button on the card'). It also explicitly limits itself to the interactive card, distinguishing it from the sibling approval_decide.

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 use the tool: only for the interactive approval card and only after a human has pressed the button. It gives an explicit exclusion ('nur fuer...' / 'only'), but it does not name an alternative tool such as approval_decide, so the routing guidance 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?

The description adds behavioral details beyond the readOnlyHint annotation: newest-first ordering, time-limited PDF preview, included fields, and the default pending filter. This gives the agent useful expectations about the output and its constraints without contradicting the annotations.

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

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

The description is compact and front-loaded with the main purpose, followed by the default behavior and the follow-up tool. It is bilingual, which duplicates content, but both languages carry the same key information and the extra length is modest and intentional for accessibility.

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 list tool with five optional parameters and no output schema, the description conveys the key return elements (approvalIds, PDF preview, cost, reason, deadlines) and the default pending state. The main missing piece is a note about pagination behavior, but limit/offset are self-explanatory from 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?

With 80% schema description coverage, the baseline is 3. The tool description does not add parameter-specific semantics; it only mentions default pending status, which relates to the 'status' parameter already documented in the schema. The 'reasoning' parameter lacks both schema and description coverage, but the high overall schema coverage keeps this at baseline.

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

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

The description states a specific verb and resource: 'Lists your account's approvals, newest first' with concrete fields (PDF preview, cost, reason, deadlines). It also distinguishes itself from the sibling approval_decide by explicitly directing the agent to use that tool for the returned approvalIds, which is more than a generic listing description.

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 clear context for when to use this tool: to retrieve approvals before making a decision, and explicitly names approval_decide as the next step. It also clarifies the default status filter ('Only the pending approvals by default'). However, it does not explicitly state when not to use it or mention alternatives like approval_status_app for single-status lookup.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context about time-limited links and the expiration-triggered renewal, which is beyond the annotations. However, it does not disclose whether new URLs are returned, whether old links are invalidated, or what happens if called before expiry.

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 compact and front-loaded with scope and action. The bilingual German/English repetition is somewhat redundant but acceptable in a multilingual context; both versions say the same thing without extra 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 one-parameter tool with safe-read annotations, the description is mostly usable: an agent knows when to call it and what it does. However, there is no output schema and no mention of the return value or what the renewed links look like, so an agent is left unsure about the tool's result.

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

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

Schema coverage is 0% and the description does not explain the approvalId parameter at all. An agent must infer from the tool name and context that approvalId identifies the relevant approval card. The description does not compensate for the lack of schema-level parameter documentation.

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 ('erneuert' / 'renews'), a specific resource ('Bildlinks der Briefseiten' / image links of the letter pages), and a clear scope ('Nur fuer die interaktive Freigabe-Karte'). It also adds the condition 'wenn die alten abgelaufen sind', which distinguishes this renewal tool from generic URL/list tools like letter_page_urls_app or template_page_urls_app.

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 explicitly says this is for the interactive approval card only, and gives a clear trigger condition: renew links when the old ones have expired. It does not name alternative sibling tools explicitly, but the 'only for the interactive approval card' constraint provides a clear exclusion boundary.

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 carry readOnlyHint=true and destructiveHint=false, so the read-only profile is covered. The description adds that it returns the current state for card rendering, but it does not describe response fields, error behavior, or auth requirements; for a read-only helper that is adequate but not rich.

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 text is compact: the scope and action are front-loaded, and the purpose clause is kept short. The bilingual duplication is the only repetition, and it serves agents that may rely on English rather than German.

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

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

For a single-parameter, read-only endpoint, the description covers what it does, when to use it, and why. It does not enumerate exact return fields, but the 'end state and countdown' clause hints at the output shape, and no output schema is provided.

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 supplies a single required approvalId (UUID), and the description links that ID to the object whose state is read ('einer Freigabe'). It does not explain the UUID format or additional constraints, but with one self-describing parameter that omission is low-impact.

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

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

The description names the exact action ('liest den aktuellen Zustand einer Freigabe' / 'reads the current state of an approval') and the resource ('Freigabe' / 'approval'), and immediately confines the tool to the interactive approval card. This clearly distinguishes it from siblings like approval_list or approval_decide.

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 'Nur fuer die interaktive Freigabe-Karte' clause is a clear when/where restriction, and the mention of rendering an old card's end state and countdown gives a concrete trigger. It does not explicitly name alternative tools, but the intended context is unambiguous.

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

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

With only bare annotations (readOnlyHint=false, destructiveHint=false), the description carries the full burden and delivers richly: it discloses side effects (reserves cost, creates a queue entry), the sequencing constraint (send only happens after approval_decide), the returned approvalId, and the dryRun exception where balance and queue stay untouched. There is no contradiction — readOnlyHint=false matches the described mutations.

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

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

The core purpose is front-loaded and every clause adds distinct behavioral information: checks, PDF creation, price calculation, cost reservation, queue entry, the approval_decide dependency, and the dryRun variant. The full German/English duplication doubles the length and the single run-on paragraph could be better separated into purpose, side effects, and variants — but there is no filler or content 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 high-complexity tool (29 params, no output schema, minimal annotations), the description covers the essential workflow, side effects, the dryRun variant, and the critical return value (approvalId). But the parameter surface remains the largest gap: with 72% of schema parameters undocumented and no required params, an agent still cannot reliably know what to pass versus what is optional enrichment.

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

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

Schema description coverage is only 28% (8 of 29 params documented), so the description should have compensated for the remaining ~21 parameters. It explains dryRun and fragments of the workflow, but leaves approvalMode, presetName, templateId, senderProfileId, mandantennummer, auditTag, reasoning, requesterContext, and most recipient fields unexplained by both schema and description. With 0 required parameters, the agent has no anchor for constructing a valid request.

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+resource combination — 'Reicht einen Brief zur menschlichen Freigabe ein, statt ihn sofort zu versenden' — which immediately distinguishes the tool from immediate-send siblings. It also names approval_decide as the explicit downstream step, so the tool's role in the workflow is unmistakable even before looking at any schema.

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

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

The description gives clear context: use this when a letter must pass human approval before sending, and it explicitly routes the follow-up through approval_decide. The dryRun explanation adds variant-level guidance. However, it never names concrete alternatives (e.g., order_send for immediate sending or letter_create_draft for plain drafts), so the when-not-to-use side is only implied rather than stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, which correctly characterizes this as a non-destructive scheduling operation. The description adds the useful detail that the call returns a job ID rather than the export artifact itself, which helps manage agent expectations. It does not disclose asynchronous behavior in more depth (e.g., that results may be delivered later or that jobs can fail after scheduling), but that is partly covered by the sibling status tool.

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

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

The description is compact: one German sentence and one English translation, with the primary purpose and return value front-loaded. Each clause earns its place by conveying the schedule semantics and the job-ID mechanism. The minor redundancy between the two languages is acceptable for bilingual coverage and does not materially bloat the entry.

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

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

For an 8-parameter tool with no output schema and 0% schema description coverage, the description provides the essential scheduling semantics but not enough detail on optional parameters, delivery behavior, or how to correlate the returned job ID with archive_export_status. The presence of the close sibling archive_export_status mitigates the gap, but a fully complete definition would explicitly mention polling and explain the optional filter/notification fields.

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

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

Schema description coverage is 0%, so the description should compensate, but it only clarifies 'format' indirectly by listing formats in prose and establishes that 'since'/'until' define the export date range. It leaves 'target', 'reasoning', 'notifyEmail', 'senderProfileFilter', and 'mandantennummerFilter' unexplained; an agent must guess their semantics from names alone. The format enum provides self-documenting options, which keeps this at a baseline 3, but the description does not compensate strongly enough for the coverage gap.

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 ('plant ein' / 'schedules'), names the resource ('Archiv-Export'), and enumerates the supported formats (GoBD-CSV, DATEV, PDF-Bundle, Mandanten-Allokation). The distinction that it returns a job ID for status polling helps clarify it from a potential immediate-export tool, but it does not explicitly differentiate it from archive_export_status, which is the obvious sibling.

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

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

The description states a clear trigger: schedule an export for a date range and receive a job ID, and the sibling list contains archive_export_status, implying that one would call this tool first and then poll with the returned ID. However, it never explicitly says 'use archive_export_status to check progress' or lists conditions under which another archive tool would be preferred, so the cross-tool routing is only implied, not stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description is consistent with that read-only profile. It adds behavioral detail beyond the annotations by disclosing that the download URL is valid for 90 days and only appears once the job is complete.

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 short and front-loaded, putting the core status and URL behavior in the first sentence. The German and English lines repeat the same information, which is slightly redundant, but the bilingual presentation still keeps the description compact and readable.

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 low-complexity tool with one required parameter and no output schema, the description covers the essential behavior: it returns job status and, when complete, a download URL with a 90-day validity. It does not enumerate possible status values or failure behavior, but that is a minor gap for a simple poll-style status tool.

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

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

Schema description coverage is 0%, so the description should compensate for missing parameter documentation. It only refers to 'an archive export job' and never explains the required jobId parameter or the optional reasoning parameter. While jobId's UUID format is self-explanatory, the description adds no parameter-level 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 description opens with a specific verb ('Liefert'/'Returns') and names the exact resource: the status of an archive export job. It also adds the completion condition and the 90-day download URL, making the tool's role unmistakable and distinguishing it from archive_export by function and name.

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

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

The description clearly frames the tool as a status-retrieval endpoint for a previously created export job, which strongly implies it should be used after archive_export to check completion and obtain the download URL. It does not explicitly name archive_export as the counterpart or state when not to use it, but the contextual signal is clear.

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

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

Beyond the minimal annotations, the description discloses rich behavior: server-side scaling to A4 PDF, optional rotation, page-count validation (max 30), automatic EXIF orientation handling, and the fact that rotation applies on top of EXIF correction. It also clearly implies a persisted write operation, consistent with 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?

The description is front-loaded with the main action and format, then covers transformation, limits, and rotation. It is concise despite being bilingual; the English repetition adds length but also makes the content robust for mixed audiences. No filler or vague marketing language.

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

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

The core operation and transformation rules are well covered, including the page-count limit and EXIF behavior. However, there is no description of the return value or result confirmation (no output schema), no explanation of the position/title/reasoning parameters, and no guidance on the precedence or mutual exclusivity of imageUrl versus imageBase64.

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

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

Schema description coverage is only 43%, so the description must compensate, but it only elaborates on rotation (mostly repeating the schema) and the accepted image formats. It does not explain title, letterId, position, reasoning, or how to choose between imageUrl and imageBase64. This leaves the majority of parameters under-documented.

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 ('Lädt ... hoch'), a concrete resource ('ein Bild (PNG/JPEG) als Anhang zu einem Partner-Brief'), and states the server-side conversion to an A4 PDF page. This clearly separates it from sibling attachment_upload_pdf, since the input format and transformation are explicit.

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: use this tool when you need to attach a PNG/JPEG image to a partner letter and have it converted to PDF. It does not explicitly name the sibling attachment_upload_pdf or state 'for PDFs use that tool instead,' but the image-only restriction and conversion behavior make the intended use evident.

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 validation behavior beyond the annotations: file size max 50 MB and merged page count max 30 pages including the letter and other attachments. This informs the agent about important failure conditions that are not visible in the schema or annotations. It doesn't mention side effects or what happens on validation failure, but the added constraints are meaningful.

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 bilingual and repetitive, but each language contains a clear purpose sentence followed by a validation sentence. There is no filler, and the action is front-loaded. The duplication makes it longer than strictly necessary, but it remains tightly structured.

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

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

The description covers purpose and validation limits, but for a 6-parameter mutation tool with no output schema it leaves gaps: it doesn't state that at least one of pdfUrl/pdfBase64 is required for a successful call, nor explain the role of position, title, or reasoning. It is adequate for basic understanding but incomplete for reliable invocation.

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

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

Schema description coverage is only 33% (only pdfUrl and pdfBase64 have descriptions). The tool description adds no parameter-level guidance: it doesn't explain letterId, title, position, or reasoning, and doesn't clarify that pdfUrl and pdfBase64 are mutually exclusive alternatives. With low schema coverage, the description fails to compensate.

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: 'Lädt ein PDF als Anhang zu einem Partner-Brief hoch' / 'Uploads a PDF as an attachment to a partner letter.' The PDF qualifier clearly distinguishes this tool from the sibling attachment_upload_image, and the partner-letter context separates it from other upload tools like letterhead_upload or signature_upload.

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 clear context for when to use the tool: when a PDF needs to be attached to a partner letter. It does not explicitly name alternatives or exclusions, such as pointing to attachment_upload_image for images, but the purpose statement leaves little ambiguity about the intended use case.

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 a concrete side effect beyond the annotations: 'Die gefundenen Logos werden als Design-Assets im Konto gespeichert' (found logos are stored as design assets in the account), which specifies what the write actually does given readOnlyHint=false. It also reveals the behavioral trait that the result is only a proposal, not a committed brand, adding commit semantics that the annotations cannot express. 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 front-loaded with the core function in the first sentence and progresses logically to side effects then workflow. However, the full German text is duplicated verbatim in English, roughly doubling length, and the trailing instruction 'Suche technisch nach brand_import_from_website / Search technically for brand_import_from_website' is a search-index artifact that adds no value to an agent deciding whether to call the tool.

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

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

With no output schema present, the description compensates by explaining what the result is (a proposal for customer review) and enumerating its contents (colours, typeface, logos, imprint data). The required follow-up step and the brandingOwnershipConfirmed flag are also covered, giving the agent the full lifecycle. The main gap is the absence of detailed response-shape expectations, but the description is adequate for a moderate three-parameter tool.

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

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

Schema description coverage is 100%, so the schema already documents websiteUrl (with example), maxLogoCandidates (with default and range), and reasoning (audit log rationale). The description reinforces the logo-candidate concept by listing 'Logo-Kandidaten' as an output, but it adds no parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate when the schema carries the full 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?

States a specific verb and resource: 'Liest eine oeffentliche Firmenwebsite aus und schlaegt daraus ein Briefkopf-Design vor' (reads a public website and proposes a letterhead design), then enumerates concrete outputs (brand colours, house typeface mapping, logo candidates, imprint data). The description explicitly distinguishes this tool from the adoption step by naming brand_kit_save as the separate follow-up, removing ambiguity with sibling 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 two-phase workflow is explicit: this tool produces a proposal for customer review, and the brand is only adopted by a subsequent brand_kit_save call carrying brandingOwnershipConfirmed. This tells the agent when this tool ends its job and where routing continues. It falls short of explicitly stating when NOT to use it or contrasting it with alternatives like letter_design_list_presets, but for a specialized import tool the workflow guidance is strong.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description only needs to add behavioral context. It adds value by specifying what the read returns: logo references, colours, and font, and that these are the saved user-facing brand values. It does not describe edge cases like missing brand data, but this is a minor gap for a simple getter with full annotation safety 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?

The core information is front-loaded and useful, but the description repeats the same content in German and English, effectively doubling its length. The sentence 'Suche technisch nach brand_kit_get' adds no informational value and reads as filler. It could be more concise without losing any 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?

For a read-only getter with one optional parameter and no output schema, the description covers the essential context: what is read, what is returned, and which downstream tools will consume the result. Exact return format and behavior when no brand values exist are unspecified, but these are low-risk gaps given the tool's simplicity and the provided 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 input schema has a single optional 'reasoning' parameter with only a maxLength and no semantic description, and schema description coverage is 0%. The description does not mention the parameter at all or suggest why an agent might supply it. Since the schema does not define the parameter's meaning, the description should have compensated but did not.

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

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

The description states a precise read operation ('Liest die gespeicherten Markenwerte') on a clear resource, and lists the returned content: logo references, colors, and font. It also differentiates itself from design tools by explicitly positioning its output as input to letter_design_preview and letter_design_save. The contrast with sibling brand_kit_save is implicit but clear from the verb and name.

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

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

The phrase 'fuer die weitere Gestaltung mit letter_design_preview und letter_design_save' gives a clear, practical context: call this tool before working on letter design. It does not explicitly state when not to use it or mention alternatives like brand_kit_save, but the intended usage context is direct and unambiguous.

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

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

With only readOnlyHint=false and destructiveHint=false, the description carries some burden and adds useful behavior: the call is a save operation, ownership confirmation is required, and the response includes the saved state and review link. It does not disclose overwrite/upsert behavior, effects on existing brand kits, or auth/rate specifics, so transparency is only partial.

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 repeats the full content in German and English and includes the unhelpful instruction 'Suche technisch nach brand_kit_save', adding length without value. Important information is spread across duplicated bilingual blocks rather than being 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 write tool with no output schema, the description usefully states that the response contains the saved state and review link and highlights the required ownership flag. However, it leaves the purpose of 'reasoning' undocumented and doesn't clarify semantics of nullable logo/font asset IDs or save behavior, so it is not fully complete for an agent.

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

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

Schema description coverage is only 33%, but the prose adds meaning to the brandKit object by mentioning logo references, colours and font, and it repeats the brandingOwnershipConfirmed requirement. The 'reasoning' parameter is not explained at all, and the optional logo/font asset IDs get no semantic guidance, so the description only partially compensates for the coverage gap.

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

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

The description names the specific action ('Saves logo references, colours and font') and the resource ('user-facing result letterhead and brand'), which makes the tool's function clear. It doesn't explicitly contrast with sibling tools like brand_kit_get or brand_import_from_website, so it misses full differentiation.

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

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

The description gives clear context for use: persisting brand assets for the final letterhead/brand output, and it states an explicit prerequisite ('brandingOwnershipConfirmed must be true') that an agent must satisfy before calling. It does not name alternatives or exclusion cases, but the context is sufficiently clear.

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

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

No contradiction with annotations — readOnlyHint=false is consistent with a creation tool. The description adds valuable behavior beyond the minimal all-false annotation set: the draft 'bleibt kostenfrei liegen, bis du ihn versendest' (cost disclosure), the recompute-and-reject arithmetic behavior, the §14 UStG mandatory-details validation, and the option to draw document numbers from a sequence. What it omits — idempotency semantics, failure modes — is secondary for a creation tool whose safety profile is already clear from annotations.

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

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

The description is front-loaded — purpose, then behavior, then pricing, then example, then next steps — and nearly every content unit earns its place. The main structural cost is the near-identical German/English duplication, which roughly doubles the length to about 600 words. Given the tool's real complexity (nested payload, 15 parameters), the size is defensible, but it is not tight.

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, deeply nested creation tool with no output schema, the description provides a strong end-to-end model: what input to send, a worked example, validation and pricing behavior, and follow-up tool routing. The notable gap is the return value — only 'letterId' is named, with no hint of the draft's status or how validation failures surface. Because there is no output schema, the description itself carries that burden and under-delivers on it.

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

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

Schema coverage is 47%, below the 50% threshold, so the description must compensate — and it does with a compact example payload that makes the core parameters concrete: quantity × unitPriceCents = lineNetCents at 19% USt, totals interlocking with line items, leistungszeitraum as von/bis dates, and recipientAddressId usage. This gives an agent a working model of the central document object. Several top-level parameters (sequenceScope, mandantennummer, reasoning, signatureId, reference) remain unexplained in both schema and description, which keeps this from a 5.

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-resource pair: 'Erzeugt aus strukturierten Belegdaten ein fertiges Dokument und legt es als Briefentwurf an' — it creates a finished billing document as a letter draft. It further distinguishes itself through unique behaviors (recomputing amounts, §14 UStG checks, DIN 5008 typesetting, number-sequence assignment) that no other sibling claims. It never explicitly contrasts with the close sibling letter_create_draft, which also creates a letter draft, so the differentiation is demonstrated but not stated.

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

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

The description gives strong post-invocation guidance: 'Nächster Schritt mit der zurückgegebenen letterId: order_send versendet den Brief, approval_submit legt ihn stattdessen einem Menschen zur Freigabe vor, letter_schedule versendet ihn später.' It also implies the use case through 'Du lieferst die Summen, FrankKi rechnet sie nach und lehnt Abweichungen ab' — this tool is for validated billing payloads. However, it never states when to use this tool instead of letter_create_draft or when it should not be used, leaving tool-selection partly to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context: signed download links are download-only, portal transmission remains the caller's responsibility, and missing exports carry specific reasons with retryable vs permanent semantics. There is 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 front-loaded with the core purpose but is quite long because it fully repeats the same content in German and English. Most sentences carry substantive information, but the bilingual duplication makes it less concise than it could be.

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

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

With no output schema, the description compensates well by explaining the meaning of referencePrefill, export URLs, error codes, export readiness semantics, and appropriate follow-up tools. An agent has enough context to invoke the tool correctly and interpret the response.

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

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

Schema description coverage is 0%, and the description does not explain the documentId parameter or the optional reasoning parameter. documentId is inferable from its name and the tool's purpose, but reasoning is completely undocumented, and the description focuses on response fields rather than input semantics.

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

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

The description states a specific verb and resource: it 'returns one document with its full payload' including line items, totals, VAT rates, reference, and letterId/orderId. This clearly distinguishes the singular retrieval behavior from sibling tools like document_list and document_create.

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 usage guidance: referencePrefill is meant to be pasted unchanged into document_create, and when an export is not supported for dunning or payment reminders, the agent should use the referenced invoice. It also names order_status as the next step for tracking shipment, clearly routing between alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description adds useful behavioral detail: scope to the user's created documents, newest-first ordering, and filter dimensions. It does not mention pagination behavior or response shape, but for a read-only list operation that is a minor 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 front-loaded with the core purpose and next-step routing, and it is not overly long. The German and English sections duplicate each other, which adds some redundancy, but it remains compact enough for an agent to parse quickly.

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 9-parameter read-only list tool with no output schema, the description covers the main scope, sort order, filters, and workflow links. It could be more complete by stating that it returns summaries (via the document_get hint) or describing the remaining parameters, but it is sufficiently complete for selection and basic 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?

With only 44% schema description coverage, the description helps by naming filter categories (type, client, recipient, referenced document) that map to documentType, mandantennummer, recipientQuery, and referencesDocumentId. However, it leaves several parameters (since, referencesNumber, reasoning) semantically uncovered and does not clarify the distinction between referencesNumber and referencesDocumentId.

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

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

The description names a specific verb ('Listet/Lists'), the resource ('deine erzeugten Dokumente / documents you created'), the concrete document types, and the ordering ('neueste zuerst'). It also names sibling tools document_get and document_create as next steps, so an agent can distinguish listing from fetching or creating.

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 context: use this tool to list/filter created documents, then follow up with document_get for full payloads or document_create for follow-up documents. It does not explicitly list exclusions or alternative list tools like letter_list, but the next-step routing provides adequate 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 only carry readOnlyHint=false, openWorldHint=false, destructiveHint=false, so the description bears the full burden. It discloses side effects (draft stored, preview PDF generated), output behavior (page count, 24h preview link, cost estimate, warnings), the content/blocks exclusivity rule, and the irreversible nature of a printed letter. This is substantial behavioral context beyond the annotations.

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

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

The description is front-loaded with purpose and outputs, then moves into the mutually exclusive body format, an example, error-recovery guidance, and next steps. It is long and repeats every point in German and English, which costs conciseness, but for a 15-parameter tool with nested blocks and no output schema the level of detail is appropriate.

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 tool with no output schema and minimal annotations, the description covers what the agent needs: return values, warnings, the draft lifecycle, the free-until-send rule, how to handle defects, and the follow-up tools by letterId. Paired with the schema's parameter descriptions, nothing essential 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 67%, so the schema does much of the work. The description adds real value by clarifying the mutually exclusive content vs blocks relationship, providing a concrete compact blocks example, and pointing to the full blocks reference resource. It does not need to re-explain every parameter given the schema's own descriptions.

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 the specific action ('Legt einen Briefentwurf an' / 'Creates a letter draft') and the resource, and immediately distinguishes the tool from send/preview siblings by saying it stores a draft and returns a preview link and cost estimate. The description also names next-step tools (letter_preview, order_send, letter_schedule), reinforcing what this tool is not.

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: create the draft, inspect the returned pages, fix defects by re-creating while it is still a draft, and only then send via order_send or schedule via letter_schedule. It names the alternatives as next steps but does not explicitly state 'use X instead of Y' or exclusions, hence 4 rather than 5.

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

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

Annotations already mark this as destructive, but the description goes further by clarifying the action is archival ('Archiviert') and that sent letters retain their original. This is valuable behavioral context beyond the annotations, explaining what actually happens and what is not destroyed.

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 action is front-loaded and the structure is logical, but the content is duplicated in German and English, and the long list of document types (cancellation, invoice, reminder, etc.) adds little functional value. A shorter single-language version would convey the same meaning more efficiently.

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, two parameters, and no output schema, the description covers the essential behavioral consequences: future sends use remaining letterheads, and sent letters are preserved. It does not mention reversibility or what happens if the design is not found, but these are minor gaps for an archive/delete 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?

The schema describes designId well enough, but the description adds no parameter-specific meaning. The optional 'reasoning' parameter is left undocumented, and schema description coverage is only 50%. The description does not compensate for this gap, though the most important parameter is already clear from the schema.

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

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

The description uses a specific verb ('Archiviert (loescht)') and resource ('gespeichertes Briefpapier (Briefdesign)'), making the action unmistakable. It also differentiates from sibling tools like letter_design_save, letter_design_list, and letter_design_preview by clearly indicating this is the archival/deletion operation.

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

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

The description provides clear decision-relevant context: after deletion, new sends use remaining letterheads, while already-sent letters keep their original for auditability. This implies when the tool should be used and states no exclusions. It does not explicitly name alternatives, but the usage context is strong.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful context by stating that the response includes the full design JSON and that designs cover all mail categories, but it does not disclose pagination, ordering, or result structure in more detail. 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 front-loaded with the main purpose and is reasonably compact, but it duplicates the full content in German and English, which adds length without new information. The mail-category sentence is contextually useful but not essential.

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 list tool with two optional parameters, the description gives the core purpose and result content. However, with no output schema and one parameter left entirely unexplained, an agent still lacks complete information about the return value and the intended use of the 'reasoning' argument.

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

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

Schema description coverage is only 50%: the 'reasoning' parameter is undocumented in both the schema and the tool description. The 'includeArchived' parameter is described in the schema, but the description itself adds no parameter-level meaning and does not compensate for the undocumented reasoning field.

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

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

The description identifies the specific resource ('Briefpapiere/Briefdesigns') and the action ('Listet'), and adds that it returns the full design JSON. It is clear and self-contained, though it does not explicitly distinguish itself from closely related siblings like letter_design_list_presets or letterhead_list.

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: designs are referenced by name or ID when sending mail, so an agent can infer that this tool is for looking up saved designs. However, there is no explicit when-to-use statement, no exclusions, and no comparison to the closely related 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 mark the tool read-only and non-destructive; the description adds useful behavior beyond that: the list grows with approved templates, the default result is text-only, and presetId triggers a real-composer preview. 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 key information is front-loaded and the structure is logical, but the German and English sections duplicate the same content and add some non-essential framing like 'grows with every curated design.' It is organized yet longer than necessary.

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

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

There is no output schema and no clarification of what fields the list returns, nor how pages and resolution affect the preview. For a tool with four optional parameters and no output schema, the description leaves too many operational details unspecified.

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

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

Schema description coverage is only 25%, and the description compensates only for presetId. The meaning and effect of pages, resolution, and reasoning are left entirely undocumented, so an agent cannot know how to set them correctly.

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

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

The description states a specific action—'Returns the owner-approved native-v2 letterheads'—and clarifies the resource as curated, safe starting points for common letter types. It is clear, but it does not explicitly differentiate from sibling letter_design_list or letterhead_list, so it stops short of a 5.

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

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

It gives a clear conditional: use the plain list for cheap text-only results, or pass presetId to render exactly one composer preview with an inline PNG. It does not name alternatives or say when not to use this tool, so it lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description aligns with them ('Der Lauf bleibt kostenfrei und der Brief bleibt ein Entwurf'), so no contradiction. The description adds substantial behavior beyond annotations: data substitution (real partner sender data, fictional recipient and sample body), fidelity guarantees ('dieselbe Aufloesung und denselben Composer wie ein echter Versand'), output format (inline PNG), the page-2-only-for-continuationHeader condition, and the precise claim that sampleVariant empty produces exactly the picture the dashboard shows.

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 and bilingual, but every clause earns its place and it is well structured: purpose first, then fidelity, output mechanics, the sampleVariant edge case, concrete use cases, and finally the cost/draft guarantee. The EN mirror duplicates the DE text, which is conventional for this audience, and the density justifies the length given the tool's complexity.

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 9-parameter tool with nested objects and no output schema, the description covers the essential call-relevant behaviors: how to select input (saved or inline design), rendering fidelity, return format (inline PNG), paging rules, and sample-variant effects. The remaining gaps are minor but real: the resolution parameter semantics and an explicit statement of how this tool differs from letter_preview.

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 schema description coverage at only 22%, the description must compensate, and it partially does: it explains the design/designId distinction ('gespeichertes oder inline uebergebenes'), the page-2 trigger ('Seite 2 nur fuer continuationHeader'), and the sampleVariant empty behavior ('Kopf und Fuss stehen echt, die Textflaeche bleibt frei'). However, the resolution parameter (thumb vs full) is not explained in either the schema or the description, and sampleSubject, reference, and reasoning also receive no semantic guidance.

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: 'Rendert ein gespeichertes oder inline uebergebenes Briefdesign' (renders a saved or inline letter design), with explicit scope of schemaVersion 1 or 2. The focus on rendering the *design* rather than a concrete letter distinguishes it from siblings like letter_preview, letter_design_save, and letter_design_delete without needing to open their schemas.

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

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

The description gives clear usage context: 'So siehst du vorab, wie Kuendigung, Rechnung, Mahnung, Angebot, Vertrag und Behoerdenpost auf diesem Briefpapier aussehen' tells the agent when a preview is useful, and 'Der Lauf bleibt kostenfrei und der Brief bleibt ein Entwurf' signals a safe, pre-send scenario. However, it never names alternatives or states when-not-to-use, and it offers no explicit differentiation from the sibling letter_preview, which is the obvious competing choice.

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 are all false, so the description carries the behavioral burden and does disclose meaningful traits: the design is fully validated before storage, checked against postal clear zones (Zustellzonen), and the tool returns a hash of stored source data. This goes beyond the schema. It stops short of stating overwrite/update behavior (what happens when designId is passed or a name is reused), but the disclosed validation and return-value behaviors are genuinely useful.

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 essential purpose and return values are front-loaded in the first sentence, which is good. However, the description is bloated: the full bilingual repetition doubles length, and the enumeration of every mail type (Kuendigung, Rechnung, Mahnung, Angebot, Vertrag, Behoerdenpost) is illustrative filler rather than load-bearing information.

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

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

For a complex tool with a massive two-version nested schema and no output schema, the description covers the core contract: what it saves, where, what it validates, and what it returns. It does not explain update semantics (passing designId to modify an existing design), the purpose of the reasoning parameter, or what happens on validation failure — gaps an agent would benefit from knowing before first 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 40% (name and brandingOwnershipConfirmed have descriptions in the schema). The tool description mentions schemaVersion 1 or 2 support, which touches design semantics, but it does not explain the undocumented parameters: designId (which doubles as an update handle given the returned designId), reasoning, or the update-vs-create meaning of brandingOwnershipConfirmed. With coverage below 50%, the description needed to compensate more than it does.

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 (saves/speichert), resource (reusable letterhead/Briefdesign), scope (partner profile), and what it returns (designId + source-data hash). It clearly distinguishes itself from siblings like letter_design_delete, letter_design_list, and letter_design_preview, which are different operations on the same resource.

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

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

The description implies when to use the tool — saving a reusable design so it carries all mail types (cancellation, invoice, reminder, etc.) — which gives contextual motivation. However, it does not explicitly state when not to use it or route to alternatives (e.g., letter_design_list_presets for preset-based designs, or letter_design_preview for checking before saving). The recovery hint about searching for letter_design_save is operational, not usage 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 mark the operation as read-only and non-destructive. The description adds useful behavioral context by stating that the response includes the letter, its associated order, and a PDF download URL that is only valid for 24 hours. It does not cover error cases, but that is acceptable for a simple read-only retrieval.

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 short, front-loaded with the main verb and resource, and includes the important URL-expiry detail at the end. The main inefficiency is repeating the same content in German and English, but overall it is compact and readable.

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 main return values and the time-limited URL, which is useful since there is no output schema. However, it does not explain the optional `reasoning` parameter or how the agent should obtain/use the IDs, leaving the invocation details partially dependent on inference.

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

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

Schema description coverage is 0%, so the description needed to explain the parameters, but it never mentions orderId, letterId, or reasoning. The parameter names are somewhat self-explanatory, yet the purpose of `reasoning` and whether both IDs are required or how they relate remain unclear.

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

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

The description states a specific action ('Returns/Liefert') and a specific resource: one of the partner's letters, together with its order and a 24-hour-valid PDF download URL. This makes the tool's core purpose clear and implicitly distinguishes it from list/search tools, though it never explicitly names a sibling.

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

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

The description implies the tool is for retrieving a single letter when its IDs are available, but it does not explicitly say when to use this tool instead of letter_list, letter_search, or letter_preview. It provides no when-not-to-use guidance or 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 indicate readOnlyHint and non-destructive behavior. The description adds one useful behavioral detail—the preview URL is only valid for 24 hours—which is beyond the schema. However, it does not describe return shape, pagination, or other response behavior, so it provides only modest extra transparency.

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 short, front-loaded with the primary action, and includes the key detail about URL validity. The bilingual repetition is intentional and not filler for a German/English tool surface.

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

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

For a simple read-only list tool with no required parameters and no output schema, the description gives enough to understand what is returned: letterheads with preview URLs. It could mention whether the list is complete or how the optional reasoning parameter is used, but those are minor gaps given the low complexity.

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

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

Schema description coverage is 0%, and the description does not explain the only parameter, 'reasoning'. Since the parameter is optional and named in a self-explanatory way, the impact is limited, but the description still does not compensate for the lack of schema documentation.

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

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

The description uses a specific verb and resource: it states it lists the letterheads stored in the partner profile. It also mentions the distinguishing detail of a short-lived preview URL, which separates it from related letter/design list 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 context is clear: use this tool to retrieve letterheads already saved in the partner profile, with preview URLs. It does not explicitly name alternatives or exclusions, but the scope is obvious enough from the description and the sibling-tool names.

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 are minimal (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description carries the burden. It discloses that PNG is printed while PDF is only filed with rendered=false, that fileUrl is preferred over base64 due to context/color concerns, and the 20MB limit. This adds meaningful behavioral context beyond annotations. It doesn't mention side effects like overwriting existing letterheads, but for this tool the key behaviors are covered.

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?

About 5 sentences covering the essential behavior, source selection, rendering limitations, and sibling routing. The bilingual structure is somewhat redundant, but each sentence adds information. The description is longer than ideal but not bloated; the front-loaded functional statement is first.

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 7-parameter upload with no output schema, the description explains the critical decisions: source priority, PNG vs PDF, exactly-one constraint, and when to use letter_design_save. The 'reasoning' parameter is undocumented and width/height semantics are thin, but the description covers the high-stakes aspects of the tool's 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?

Schema coverage is 86% (6 of 7 parameters described). The description adds semantics beyond the schema by explaining the source selection logic ('genau eine von beiden'), the PNG/PDF rendering difference, and why fileUrl is preferred. However, widthMm/heightMm/displayName are only described as 'optional' in both schema and description without further guidance, and the 'reasoning' parameter is completely undocumented. Still, the core parameter semantics are substantially enriched.

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 ('Lädt ... hoch und speichert'), a resource ('Briefkopf'), and target ('Partnerprofil'), and distinguishes from letter_design_save and blocks. It clearly explains what this tool does and what it does not do. The sibling differentiation is explicit with 'dann letter_design_save' and 'der Brieftext bleibt den blocks vorbehalten.'

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 explicitly states the source preference (fileUrl bevorzugt), the mutual exclusivity ('genau eine von beiden'), and when to use letter_design_save for rebuilding letters. It gives clear context for what belongs here versus the blocks. This is explicit when-to-use guidance with alternatives named.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe read-only nature is covered. The description adds the scope 'des Partners' and the filtering dimensions, but it does not disclose pagination behavior, ordering, or return format; with the annotations doing the heavy lifting on safety, this is adequate but not rich.

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 compact bilingual sentence pair, front-loaded with the core action and containing no filler. The EN repetition is mildly redundant but serves clarity for multilingual agents, so it remains appropriately concise.

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

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

With 7 parameters, no output schema, and a closely related sibling (letter_search), the description is under-specified. It omits pagination/limit/offset semantics, return shape, and any guidance for choosing between letter_list and letter_search, leaving a substantial gap 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 0%, so the description must compensate. It adds meaning by mapping filter concepts to parameters: recipient name (recipientNameContains), subject (subjectContains), status (statusFilter), and time (since). However, it does not explain limit, offset, or reasoning, which remain ambiguous despite the low 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 clearly states a specific action ('Listet'/'Lists') and a specific resource ('Briefe des Partners'/'partner's letters'), and it names the main filter dimensions (recipient name, subject, status, time). It does not explicitly distinguish itself from the sibling tool letter_search, which likely overlaps in function, so it is clear but not fully differentiated.

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 what the tool does and mentions optional filters, but it gives no guidance on when to choose letter_list over letter_search or letter_get. No exclusion criteria or alternative routing is provided, leaving the agent to infer usage from the name alone.

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 convey read-only and non-destructive behavior. The description adds relevant context beyond those annotations: the links are time-limited, they expire, and renewal applies only to the interactive letter view. It does not describe the return format, but for a read-only helper this is a minor 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 compact and front-loaded: scope, action, then trigger condition. The English translation is a deliberate duplication that improves accessibility without adding unnecessary 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 simple one-parameter, read-only, non-destructive helper, the description covers the main facts: what it does, when to use it, and its scope. It does not specify the exact return shape of the renewed URLs, but the tool name and verb make the outcome reasonably clear.

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

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

The schema has one required parameter, letterId, with no description and 0% schema description coverage. The description never explicitly explains that letterId identifies the letter whose page link URLs should be renewed; this must be inferred from the tool name and the word 'Briefseiten'.

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

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

The description states a specific action ('renews the time-limited image links'), a specific resource ('letter pages in the interactive letter view'), and an explicit scope boundary ('Nur fuer die interaktive Brief-Ansicht'). This distinguishes it from sibling page-URL tools for approvals and templates.

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 an explicit trigger condition ('when the old ones have expired') and an explicit when-not constraint ('only for the interactive letter view'). An agent can confidently decide when to call this tool and when to look at other view-specific tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description adds meaningful beyond-annotation context: the preview is free of charge, the letter stays put, an unsaved design creates no account entry and only applies to this one preview, and a passed design takes precedence over designId. It also discloses form-mode behavior (recipient block/date/subject dropped, content starts at 27 mm). 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 front-loaded with the core purpose and includes genuinely useful workflow details. However, it is very long and duplicates the entire German content in English, roughly doubling its length. It could be tightened substantially without losing information.

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

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

For a 13-parameter tool with no output schema, the description covers the essentials: return values (PNGs, PDF link, page count, price, designRender with documentMode and bodyStartMm), side effects (free, letter stays put, no account entry), form-specific rendering behavior, iteration workflow, and a pointer to frankki://blocks-guide for the full block reference. Nothing critical for invoking the 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 77%, so the schema already documents most parameters. The description adds value with a compact runnable blocks example (heading/table/totals), a design:{schemaVersion,documentMode:'form'} snippet for forms, and the invariant that input comes via letterId or inline content OR blocks. This meaningfully supplements the schema without being redundant.

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 names the action (pruefen/rendern), the resource (Brief/Entwurf/Formularvorschau), and the concrete outputs (Inline-PNGs, PDF-Link, Seitenzahl, Preis, designRender). It clearly frames letter_preview as a mandatory verification step before template_save/template_release, which helps distinguish it from the save/release flow. It does not explicitly contrast it with letter_design_preview or template_preview, but the letter/draft/form scope is unmistakable.

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 an explicit iterative workflow: preview first, compare PNG pages against the original, correct blocks/design, preview again, and only then use template_save and template_release. It also gives a specific rule for standalone forms: always preview with design.documentMode='form'. It does not explicitly state when not to use sibling preview tools, which keeps it just 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?

Annotations only say the tool is not read-only and not destructive, so the description carries the behavioral burden. It meaningfully discloses non-obvious side effects: checks and pricing happen immediately, costs are reserved, and the actual send later reuses the same send pipeline. It does not cover cancellation or how to identify the created schedule, but the core side effects are transparent.

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 German and English halves are near-verbatim duplicates, which adds length, but each half is tight, front-loaded with the core action, and followed by the key cost-reservation side effect. There is no filler or irrelevant detail, and the bilingual structure is reasonable for this API.

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

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

With 22 parameters, no output schema, and only 45% schema coverage, the description needs to explain return behavior or at least point to related lifecycle tools. It does not describe what the tool returns, how to cancel a scheduled send, or that schedule_list_or_cancel exists. For a tool that reserves real costs, this operational context is a significant gap.

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

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

The input schema covers only 45% of parameters, and the description does not compensate for the gap. It restates the three modes but does not map them to specific parameters or explain undocumented fields such as color, express, auditTag, deliveryType, senderProfileId, or includeSignature. For a 22-parameter tool, this leaves too much to inference.

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: it schedules the sending of an existing draft for a later time. It also enumerates the three scheduling modes (fixed, relative delay, recurring cron), which clearly distinguishes it from immediate-send siblings like order_send and from schedule management tools like schedule_list_or_cancel.

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 target use case is clear: use this tool when an existing draft should be sent later rather than immediately. However, it does not explicitly name alternatives or exclusion conditions, such as 'for immediate sending use order_send' or 'for managing existing schedules use schedule_list_or_cancel', so it provides clear context without explicit 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful scope information (which fields are searched) but does not disclose other behavioral traits such as result ordering, matching semantics, or response structure beyond the schema defaults.

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 one concise sentence in German plus its English translation, with no filler. The key search behavior and scope are front-loaded before any schema details.

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 5 parameters, the description plus schema covers the search scope, required/optional parameters, and pagination. Because there is no output schema, a small gap remains around what the returned matches look like, but this is unlikely to block 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?

With schema coverage at 60%, the description becomes important for the undocumented 'query' parameter, and it delivers by specifying that the query applies to subject, recipient name, and letter content. It does not explain the 'reasoning' parameter, but the other three parameters already have schema descriptions, so the overall semantic gap is small.

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' / 'searches') and resource ('Briefe des Partners' / 'partner's letters') and names the exact searchable fields: subject, recipient name, and letter content. This clearly differentiates the tool from sibling list/retrieval tools like letter_list and letter_get, which do not perform full-text content search.

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 that this is the tool to use for full-text search over letter fields, but it does not explicitly state when to prefer it over alternatives such as letter_list or letter_get, nor does it give exclusions. No alternative tool is named, so the agent must infer the selection from the word 'Freitext'.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safe read-only nature is covered. The description adds transparency by enumerating exactly what the tool returns (addresses, category, monthly budget, retention period, letter count), which is 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 a single clear sentence, but the English sentence fully duplicates the German sentence without adding information. This repetition costs tokens without benefit, though the field list is dense and relevant.

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 no output schema and three undocumented parameters, the description covers the return fields but leaves critical invocation details unaddressed: how to identify the Mandant, whether mandantId or mandantennummer is preferred, and what the optional reasoning parameter is for. It also does not distinguish when to use this versus list/search siblings.

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

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

Schema description coverage is 0%, and the description does not explain the meaning or usage of mandantId, mandantennummer, or reasoning. The parameter names are somewhat self-explanatory, but the description adds no input guidance, leaving ambiguity especially because no parameters are marked required.

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 ('Liefert' / 'Returns') and the resource ('einen Mandanten'), and lists the specific data fields returned. It is distinguishable from sibling tools like mandant_list and mandant_search by its singular framing, though it does not explicitly contrast itself with them.

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

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

The description provides no guidance on when to use this tool rather than alternatives such as mandant_list or mandant_search. It also fails to state whether callers should supply mandantId or mandantennummer, or when this single-record getter is appropriate.

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

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

Annotations already disclose readOnlyHint=true and destructiveHint=false, so the description does not need to repeat that this is a safe read. It adds the partner-scoped dataset and optional filtering behavior, but it does not mention pagination, ordering, or edge-case behavior.

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

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

A single bilingual sentence with no filler. The verb and resource are front-loaded, and the English equivalent is compact and useful rather than redundant.

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

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

For a simple read-only list operation, the description conveys the core purpose and main filter options. However, with seven parameters and no output schema, it omits the since filter, pagination behavior, the reasoning parameter's purpose, and any description of the return shape.

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

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

Schema coverage is only 43%, with limit, since, and offset documented in the schema. The description adds meaning for otherwise undocumented filter parameters by mapping 'Suchbegriff' to searchQuery, 'Kategorie' to kategorieFilter, and 'Tag' to tagFilter. However, the reasoning parameter remains completely unexplained.

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 clear verb ('Listet') and resource ('Mandanten des Partners'), plus optional filters by search term, category, or tag. It does not explicitly differentiate from the sibling mandant_search, so the agent must infer the list-versus-search boundary.

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?

Provides no guidance on when to use this tool instead of alternatives such as mandant_search or mandant_get. The description restates the operation and optional filters, but it never says when this is the right choice or when it is not.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail beyond those annotations: each result identifies which column matched the query, helping the agent interpret hits. It does not cover pagination behavior, but limit and offset are documented in the schema.

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

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

The content is well ordered, with the main search behavior first and follow-up actions after. However, the full German text is duplicated in English, which doubles the length without adding new information. It is still readable and front-loaded, but not as tight as it could be.

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

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

There is no output schema, so the description should clarify the return shape; it partially does by saying the matching column is named per hit and that a mandantennummer is available for next steps. It lacks explicit guidance on exact result fields, pagination behavior beyond schema basics, and how this tool relates to sibling search/list tools such as mandant_list or address_search_company.

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 60%, and the key parameter 'query' has no schema-level description. The description compensates by explaining that query can match Mandantennummer, Name, Tags, or Sachbearbeiter. The remaining parameters (limit, offset, since) are already described in the schema, though 'reasoning' remains unexplained.

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 ('Sucht') and resource ('Mandanten') and enumerates the search criteria: client number, name, tags, or case handler. It also notes that each hit names the matching column, which makes the tool's behavior concrete and distinct from generic list or get tools like mandant_list and mandant_get.

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

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

The description implies when to use this tool—when you need to locate a Mandant by partial search criteria—and provides clear next-step routing by naming document_create, mandant_get, and letter_create_draft as follow-ups. It does not explicitly state exclusions or compare itself with alternatives like address_search_company, but the workflow context is clear.

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

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

Annotations already mark the tool as readOnly and non-destructive; the description adds context by explaining that it validates the token, checks the processing chain, reports setup prerequisites, and optionally probes the render path. This goes beyond the annotations without contradicting them.

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

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

The description is front-loaded with the core purpose, but it repeats the same content in German and English, doubling its length without adding new information. The sentences are otherwise informative and well structured.

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

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

For a read-only health-check tool with rich annotations, the description covers what is checked, what the setup report contains, and how the optional render probe works. It does not describe the exact response shape, but the absence of an output schema is partially mitigated by the detailed description of what is reported.

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 checkRender parameter is described both in the schema and in the tool description, but the reasoning parameter has no schema description and is not mentioned in the tool description at all. With 50% schema coverage, the description needed to compensate for the undocumented parameter, and it fails to do so.

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 is a health/echo probe that verifies the partner token and the end-to-end processing chain. It also mentions the specific setup report and optional render check, leaving no ambiguity about what the tool 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?

It gives explicit guidance to call this tool before building a template that will need to be viewed, and explains when checkRender should be enabled. It does not name alternative tools or explicit exclusions, but the context is clear enough for an agent to decide when to use it.

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

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

Annotations already flag the tool as destructive. The description adds valuable behavioral context: the refund is credited to the wallet rather than the card, already-printing orders are rejected, and chat-approved sends can be stopped before dispatch. It does not cover idempotency or invalid ID combinations, but the core behavior is clearly disclosed.

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 outcome, but the entire content is duplicated in German and English, roughly doubling the length without adding new semantic information. It is organized well but not concise.

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 both cancellation modes and the wallet-credit side effect well. However, the schema declares zero required parameters, and the description never explicitly states that one of orderId or approvalId must be provided. With no output schema, return behavior is also left unspecified, which is a meaningful gap for a destructive tool.

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

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

Schema coverage is 75% and the description reinforces the orderId vs approvalId distinction already present in the schema. It adds real-world framing around printing state and timing windows, but it does not explain the 'reasoning' parameter and adds little meaning to 'reason' beyond what the schema already provides.

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

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

The description states a specific verb and resource ('Storniert einen Brief') and clearly distinguishes the two invocation modes: orderId for existing orders and approvalId for chat-approved sends. It also names the outcome (credit to wallet), which separates it from siblings like order_send and order_status.

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-to-use guidance is provided for both modes: orderId works within the cancellation window, already-printing letters are cleanly rejected, and approvalId stops a chat-approved send within a 10-minute grace window. It never explicitly names alternative tools or says 'use X instead', so it is strong but not maximally complete.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so this is known to be a safe read operation. The description adds useful behavioral context beyond that: the returned URL expires after 90 days, the record comes from the GoBD archive, and the result includes postmark and provider details. 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 definition is front-loaded with the primary purpose and provides a concise list of returned data. The German and English versions duplicate the same content, but this is reasonable for a bilingual tool and does not make the description 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?

For a simple read-only tool with one required UUID parameter and no output schema, the description explains what the caller receives in enough detail. The main gap is the unexplained 'reasoning' parameter, but this does not undermine the overall usability.

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

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

Schema description coverage is 0%, so the description must compensate for the input schema's lack of parameter documentation. It adds meaning for orderId by linking it to a sent order, but the optional 'reasoning' parameter is never explained, and no parameter-level detail is given in the schema either.

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

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

The description uses a specific verb ('Liefert'/'Returns') and a specific resource (Einlieferungsbeleg for a sent order), and enumerates the concrete result components: download URL valid for 90 days, postmark, mail provider, and GoBD archive record. This clearly distinguishes it from sibling tools like order_status or order_send.

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 conveys that this tool applies to a 'versendeten Auftrag' (sent order), which gives clear context for when to use it. However, it does not explicitly name alternatives, exclusions, or when not to use it, so it stops short of the highest guidance level.

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

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

The description adds meaningful behavioral context beyond the annotations: it explains the price/billing behavior (reserved balance or booked charge stays), the status precondition, and the expected failure code. This is useful given destructiveHint=true, though it does not fully describe downstream side effects of releasing for sending.

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 efficient and front-loaded: the main action comes first, followed by billing behavior and the critical status constraint. The German/English duplication adds length, but both versions contain no filler and each sentence contributes useful information.

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

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

For a targeted fix-and-resubmit operation, the description covers purpose, precondition, failure mode, and pricing side effects. It lacks explicit guidance on reasoning and clientOrderId, and there is no output schema, but the core calling context is clear enough for correct invocation.

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

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

Schema description coverage is only 25%, and the description does not compensate for the undocumented parameters. It clarifies the recipient-related purpose but says nothing about reasoning or clientOrderId semantics, and orderId is only implicit through 'eines Briefs'. This leaves a meaningful gap for an agent selecting values.

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

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

The description names a specific verb and resource: it corrects the recipient address of a letter awaiting a fix and releases it for sending again. It also states the required status, which distinguishes this tool from generic sending or cancellation tools like order_send and order_cancel.

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 states when to use the tool: only for orders with status awaiting_partner_fix. It also states that any other status results in ORDER_NOT_FIXABLE. However, it does not explicitly name alternative sibling tools for other use cases, so it stops short of full alternative 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 only say destructiveHint=true/readOnlyHint=false; the description adds a wealth of behavioral context beyond that: the default approval-queue behavior with a human deciding via approval_decide, dryRun semantics (free, letter stays put, probe letterId returns NOT_FOUND in letter_get/letter_preview), wallet reservation for draft/review modes with INSUFFICIENT_FUNDS, and PRICE_CHANGED abort behavior. The description aligns with destructiveHint=true (sends physically, charges) rather than contradicting it.

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

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

The opening sentence front-loads the purpose well and every sentence carries information, but the full German text is then repeated verbatim in English, roughly doubling the length. For an LLM parsing this, the duplication is pure overhead; a single well-structured bilingual or English-only version would be tighter. Dense content earns it a 3 rather than lower, but it is not concise.

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

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

For a destructive, money-moving tool with 40 parameters, nested objects, no output schema, and an approval workflow, the description covers a remarkable amount: input modes, preview prerequisite, approval routing, wallet reservation, dryRun side effects, error conditions, price-abort semantics, idempotency, and recovery paths, plus a pointer to the frankki://blocks-guide resource. The main omission is any hint about the success response shape, which matters more here because no output schema exists.

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 53%, so the description carries real weight and it delivers on the highest-stakes parameters: the letterId-vs-inline distinction, the content-OR-blocks exclusivity with a concrete compact blocks example, dryRun semantics, and the shipping_quote priceVersion flow. Many remaining parameters already have strong schema descriptions (clientOrderId, approvalMode, designId, templateVersionId). Minor gap: some parameters like color, express, subject, recipient fields get no description-level attention, but they are low-complexity.

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?

Opens with a specific verb+resource: 'Versendet einen Brief physisch per Post' and then enumerates the full pipeline (checks sender details, recipient address, AVV, limits; creates PDF; calculates price; releases send). It actively differentiates from siblings by name (shipping_quote, letter_preview, letter_create_draft, order_cancel, order_fix_resubmit), so an agent can tell exactly which operation this is.

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-to-use guidance throughout: recommends previewing via letter_create_draft/letter_preview before sending, instructs use of letter_create_draft for plain drafts without wallet cover, routes cost-estimation-during-planning to shipping_quote, and names recovery paths (order_cancel, order_fix_resubmit). The schema's approvalMode description reinforces the letter_create_draft alternative. No exclusions are left to inference.

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

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

Annotations only say destructiveHint=true, but the description goes much further: it explains per-item validation and pricing, failure continuation, stopOnError, one combined approval, full send on approval, refund on rejection, and dryRun behavior. This is rich, accurate behavioral disclosure beyond the annotations.

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

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

The description is front-loaded and contains useful detail, but it is long because every point is repeated in both German and English. It could be more concise with one language or structured bullets 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?

For a complex batch-send tool, the description covers the key operational context: approval flow, error behavior, cost implications, dryRun, and side effects. No output schema exists, but the description provides enough for an agent to invoke the tool correctly and understand what will happen.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by connecting items, dryRun, and stopOnError to the actual batch execution model and approval semantics, which the schema alone does not convey.

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

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

The description clearly states a specific verb and resource: sending multiple letters as one batch. It also distinguishes itself from single-send siblings by emphasizing the batch, the single approval, and options like stopOnError and dryRun.

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

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

The description makes the batch context and approval flow clear, so an agent can infer when to use it. However, it never explicitly says when to prefer this over order_send, shipping_quote, or other related tools, nor does it state exclusions or 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?

The annotations already indicate readOnlyHint=true and destructiveHint=false, and the description adds valuable behavioral context: tracking numbers appear only for registered mail, tracking history is chronological German tracking, and the response includes delivery estimate and cancellation availability. It also explains the awaiting_partner_fix state. 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 German description is well-structured and front-loaded with core behavior before conditional routing. However, the entire text is repeated verbatim in English, doubling the length without adding new information and reducing conciseness.

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

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

With no output schema, the description compensates well by enumerating the returned fields and status-dependent next steps. The main gap is the unexplained reasoning parameter; otherwise an agent has sufficient context to invoke the tool and interpret the result.

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

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

The schema has 0% description coverage and the description does not explain the orderId or reasoning parameters. While orderId is inferable from its name and UUID format, the optional reasoning field is entirely opaque, leaving the agent unsure what to pass or why.

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 concrete verb ('Liefert'/'Returns') and names the exact resource: the current status of an order. It also enumerates the specific payload fields (German chronological tracking history, tracking number for registered mail, estimated delivery, cancellation availability), which clearly distinguishes it from mutation siblings like order_send or order_cancel.

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 explicit conditional routing: on status awaiting_partner_fix, call order_fix_resubmit; while cancellable is true, order_cancel can still stop the send. This gives an agent clear when-to-use and when-to-hand-off guidance beyond simply invoking the 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 only signal non-readonly, non-destructive mutation, so the description carries the behavioral burden and delivers meaningfully. It discloses that the name is unique per partner (implying duplicate-name semantics), that limits are stored unmodified as a note, and critically, that the saved limits are not enforced — saving the agent from a wrong mental model. It does not specify whether a duplicate name overwrites or errors, which would have made this a 5.

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

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

The description is efficiently structured: the core verb-object is front-loaded in the first sentence, followed by two short sentences that add uniqueness and non-enforcement semantics. Being bilingual (German/English) doubles length, but both versions are complete and every sentence earns its place. No filler or repetition of schema data.

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 a complex nested-object parameter and no output schema, the description covers purpose, uniqueness, and the non-enforcement nuance well. However, it omits what happens on duplicate name (overwrite vs. error), any return-value expectations, and any mention of the reasoning parameter. These are notable gaps for an agent deciding how to invoke and interpret the call.

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

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

Schema coverage is 67%, with name and preset documented but reasoning having no description at all. The description adds genuine semantic value for the preset parameter — clarifying that limits within it are stored as-is and serve only as a note — which is beyond the schema text. However, it does not cover the undocumented reasoning parameter, so it only partially compensates for the coverage gap.

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: 'Saves a named preset (configuration bundle) in the partner profile.' It goes beyond a bare statement by defining what the bundle contains and clarifying a key semantic boundary — that limits inside the preset are stored as notes and not enforced, which differentiates it from limit-setting or enforcement tools among the siblings. It does not explicitly name a sibling tool, but the functional scoping is strong enough to avoid confusion with template_save, letter_design_save, or brand_kit_save.

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 conveys implied usage context: it tells the agent this tool persists a configuration bundle and that enforcement happens 'exclusively on the account and sub-wallet limits set in the web app.' This indirectly warns the agent not to expect limit enforcement from this tool, but it never states explicit when-to-use or when-not-to-use conditions, nor does it name an alternative tool. The guidance is inferable rather than direct.

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, so the safety profile is covered. The description adds important behavioral context beyond annotations: the prices are examples for a one-page black-and-white standard letter within Germany, and the real price depends on additional factors. This sets correct expectations about the nature of the 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 well-structured: it states the purpose, gives trigger keywords, then provides the caveat and the alternative tool. The only redundancy is the full bilingual repetition (German and English versions of the same content), which is acceptable for accessibility but slightly reduces conciseness. Every sentence earns its place in terms of 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 simple read-only pricing tool with no business parameters, the description is complete. It explains what data is returned (tier thresholds and example prices), the exact assumptions (one-page B&W standard domestic letter), and routes to the relevant sibling tool for real quotes. The absence of an output schema is mitigated by a clear textual description of the return concept.

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

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

The schema has only one optional 'reasoning' parameter with no description, but it is a generic meta-parameter rather than a business input. The description effectively covers the tool's domain semantics by explaining what data is returned, so no additional parameter guidance is necessary. The lack of a business parameter list is compensated by the description's clarity about scope.

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 ('Returns FrankKi's volume tiers') and resource, clearly stating what the tool provides: bulk discount tiers with the monthly quantity thresholds and example per-letter prices. It also distinguishes itself from shipping_quote by explicitly stating the tool gives example prices only, not real quotes.

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

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

It explicitly tells the agent when to use the tool: 'Use this when someone asks about bulk discounts, volume pricing or enterprise pricing.' It also indicates when not to use it by directing real price calculations to shipping_quote, making the decision boundary unambiguous.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the scope of returned data, but does not disclose any behavioral traits such as aggregation behavior, latency, or auth requirements. It adds some value beyond annotations without contradicting them.

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

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

The description is a single front-loaded sentence that conveys the tool's scope and contents efficiently. The bilingual repetition adds length but serves multilingual users; it remains appropriately sized and well structured.

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

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

With no output schema, the description carries the burden of explaining return values, and it lists the major categories (address, signature, letterhead, presets, wallet, pricing). It does not detail the reasoning parameter, but since the tool is callable with zero parameters and returns a summary, the coverage is sufficient for an agent to use 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?

There is one optional parameter, 'reasoning', with zero schema description coverage (0%). The description does not explain the parameter's purpose or format. Since the schema gives no help and the description does not compensate, parameter semantics are weakly documented.

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 ('Liefert das Partnerprofil im Überblick') and enumerates the exact contents (sender address, signature, letterhead, presets, wallet summary, pricing model). This clearly distinguishes it from sibling tools like sender_profile_get or wallet_balance, which return narrower data.

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 getting a consolidated profile overview, but it does not explicitly state when to prefer it over individual sibling tools or when not to use it. It provides context (overview vs detail) without naming alternatives or exclusions.

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

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

Annotations already state destructiveHint=true and readOnlyHint=false, so the destructive nature is covered. The description adds one useful behavioral detail: cancellation releases the reserved amount. However, it does not discuss irreversibility, permissions, or what happens when no matching scheduled send exists, so the addition is modest.

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

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

The description is two short bilingual sentences with no wasted words. It front-loads the main action and the cancellation side effect, and it avoids repeating schema-level parameter details.

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 dual-mode tool with no required top-level parameters and no output schema, the description is minimal: it does not state that action is practically required, describe list versus cancel responses, or clarify that cancel is the destructive branch. The schema compensates for some of this, so the description is adequate but has clear gaps.

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

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

The input schema already describes action, dryRun, scheduleId, and statusFilter with 80% coverage. The tool description adds little parameter-level meaning beyond connecting cancellation to the release of the reserved amount. With high 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 specific verbs ('listet auf', 'bricht ab') and a clear resource ('geplanten Sendungen des Partners'), and adds a meaningful side effect ('reservierte Summe wird freigegeben'). It clearly distinguishes the list and cancel behaviors, so an agent can tell what this tool does without relying on the name alone.

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

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

The description provides no guidance on when to choose this tool over sibling tools such as letter_schedule or order_cancel, and it does not mention exclusions, prerequisites, or alternative tools. The intended use is only implied by the name and action enum.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is well covered. The description adds useful return-content expectations but does not mention error cases, authorization requirements, or other behavioral aspects. There is 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 short sentences, front-loaded in German with a direct English equivalent. There is no filler or unnecessary repetition beyond the bilingual translation, which is appropriate. It is concise and easily scannable.

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 getter with read-only annotations and a required ID, the description is adequate at a high level but incomplete: it omits parameter semantics, especially for reasoning, and gives no guidance on when to use this tool over sender_profile_list or sender_profile_validate. It also lacks output structure, though the listed fields partially compensate for the missing 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 0%, so the description needed to explain both parameters, but it mentions neither profileId nor reasoning. profileId can be inferred as the target profile identifier, but reasoning is left entirely undefined. The description therefore adds no parameter meaning 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 uses an action verb ('Liefert/Returns'), names the resource ('ein Absenderprofil/sender profile'), and specifies scope ('ein einzelnes/single'), which distinguishes it from sender_profile_list. It also lists the key returned content: mandatory details, bank account, and disclaimer.

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?

No explicit when-to-use or when-not-to-use guidance is provided. The word 'single' and the required profileId parameter imply this tool is for retrieving one profile by ID, but the description does not direct agents away from sender_profile_list or sender_profile_upsert. Usage context is only inferred.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds useful behavioral context about what the result includes (legal form, mandatory-details completeness) and the scope ('all profiles'). However, it does not mention ordering, pagination, empty results, or any partner-identification prerequisite.

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 short and front-loaded with the verb and object. The bilingual duplication adds a little length but is compact and useful for language coverage. Every key point fits in two concise statements.

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?

This is a simple read-only listing tool, and the annotations cover side-effect safety. However, the undocumented 'reasoning' parameter and the lack of any guidance about sibling tools leave gaps that an agent must resolve by trial or external knowledge.

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

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

Schema description coverage is 0%, and the only parameter, 'reasoning', is left entirely unexplained in both the schema and the description. The description does not compensate for this gap, so an agent cannot know what value to pass or whether the parameter affects the listing behavior.

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 ('listet/lists') and a clear resource ('alle Absenderprofile des Partners / all of the partner's sender profiles'). It further distinguishes the tool by specifying the returned attributes: legal form and completeness of mandatory details. This separates it cleanly from siblings like sender_profile_get or sender_profile_upsert.

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 the scope ('all profiles of the partner') but provides no guidance on when to choose this tool instead of sender_profile_get, sender_profile_validate, or other list tools. No alternatives or exclusion conditions are mentioned, so the agent must infer usage purely from the name.

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 are minimal (three false hints), so the description carries the behavioral burden. It discloses the tool's most non-obvious contract: a partial/incomplete profile is still saved and missing fields are reported back, rather than the call failing validation; and sending is gated on completeness. This is exactly the kind of behavior an agent cannot infer from the name or schema and it is clearly stated.

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

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

Three tight sentences per language, each carrying one distinct fact: purpose/scope, the partial-save-and-report behavior, and the sending requirement. The content is front-loaded and every clause earns its place; the only length comes from the deliberate bilingual (DE/EN) duplication, which is an accessibility choice rather than bloat.

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 9-parameter write tool with nested objects and no output schema, the description covers the key uncertainty an agent faces — what happens on incomplete input (saved, missing fields reported) — and sketches the sending consequence. The remaining operational details (id-based upsert selection, isDefault default-marking side effects) live in the schema, which is rich enough to carry them.

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 89% (only 'reasoning' lacks a description), and the schema descriptions are already rich — id's create-vs-edit semantics, isDefault's side effects, defaultDesignId's null-vs-omit distinction. The description's field list (Rechtsform, Pflichtangaben, Bankverbindung, Haftungsausschluss, Briefpapier) merely mirrors the schema property names without adding deeper meaning, so the baseline 3 is correct.

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

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

The description opens with a specific verb-resource pair — "Legt ein Absenderprofil an oder bearbeitet es" (creates or edits a sender profile) — and enumerates the affected fields (Rechtsform, Pflichtangaben, Bankverbindung, Haftungsausschluss, Standard-Briefpapier). The create/edit (upsert) semantics clearly distinguish it from the read-oriented siblings sender_profile_get, sender_profile_list, and sender_profile_validate.

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 conveys workflow context: incomplete profiles are saved and missing fields reported for step-by-step completion, and sending requires complete mandatory details. This implies when the tool is useful (iterative profile setup), but it never names alternatives or states explicit when/when-not conditions — the routing to sender_profile_validate for per-legal-form required fields appears only in the schema, not in the description.

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