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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description nevertheless discloses valuable behavior: null vs empty-array semantics for failed assignment lists, the guard that 'keine Zuordnung' is only claimed when the API said so, and the API-call budget ('Höchstens 5 Aufrufe'). It doesn't discuss pagination of the assignment rows, but the max_rows note partially covers that.

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

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

Front-loaded with the core purpose and the question it answers, followed by invocation rules and behavioral caveats in logical order. It is dense and every sentence carries information, though the 'Ersetzt das Paar...' sentence is somewhat list-like and could be tightened.

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 an output schema exists, the description needn't explain return fields, and it doesn't. It covers what the schema and annotations can't: sibling replacement, exactly-one-of, null-vs-empty semantics, file exclusion, and the API call limit. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond the schema: it states the exactly-one-of constraint on the two ID fields, clarifies that string-form IDs from search results must be passed unquoted, and warns that receipt 1590 and transaction 1590 are distinct entities. That is genuine added value over the schema's per-parameter text.

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

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

Specific verb+resource: 'Holt einen Beleg oder eine Zahlung samt allen zugeordneten Gegenstücken'. It even states the user questions it answers ('welcher Beleg gehört zu dieser Abbuchung'). It explicitly distinguishes itself from the four siblings it replaces (bb_receipts_get/list_transactions and bb_transactions_get/list_receipts), making its scope unambiguous.

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

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

Explicit guidance: 'Genau eines der beiden Kennungsfelder setzen' tells the invocation rule, and 'Ersetzt das Paar X und Y' tells the agent when to prefer it over the sibling pairs. It also names a when-not case ('Die Belegdatei kommt nie mit, dafür bb_receipts_get'), routing the file-retrieval use case elsewhere.

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 read-only nature is clear from 'Liefert' and aligns with readOnlyHint=true, idempotentHint=true, and destructiveHint=false. It also notes server-side truncation and a maximum of 2 API calls, giving useful behavioral expectations.

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 structured around purpose, usage, edge cases, and sibling differentiation. It avoids redundant restatement while still conveying the important operational caveats.

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?

It covers purpose, usage, account resolution, truncation behavior, empty-ledger semantics, API-call limits, and sibling-tool routing. With output schema present and annotations consistent, the description is complete for this read-only balance 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 100% for all 6 parameters, and the description adds meaning for account resolution, date_from behavior with pre-period Saldo, max_rows middle truncation, and response_format. The remaining parameters are clearly documented in the schema.

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

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

States it returns a Kontenblatt with fortgeschriebenem Saldo and answers specific questions about Kassenbestand and PayPal. It also explicitly distinguishes itself from bb_reports_get_ledger for balance queries versus the 24-field ledger tool.

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

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

Explains that account accepts a Kontonummer or Zahlungskonto name, directs Sachkonten to bb_masterdata_search, and says it replaces bb_reports_get_ledger for Kontostand questions. It also includes edge-case guidance that an empty Kontenblatt is not a 0,00 Saldo.

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

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

Goes well past the annotations by disclosing that the comment is visible to every user of the tenant, that no API endpoint exists to read, change, or delete comments, that the response returns no identifier for the created comment, and that the write hits real accounting data with no undo path. These are exactly the operational facts an agent needs before committing an irreversible write.

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

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

Front-loads what the tool does, then layers constraints and side effects in a logical order with no filler sentences. It is a touch long and leans on comma splices rather than clean clause separation, but every sentence carries a distinct fact.

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 irreversible create against live data, the description covers target selection, visibility, the absence of read/update/delete endpoints, and the missing return identifier—even though an output schema exists. Nothing needed to invoke it safely is missing.

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

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

Schema description coverage is 100%, so all three parameters are already fully documented in the schema, including the exactly-one-identifier rule and the 'pass as integer, not string' note. The description only restates the either/or constraint, adding no semantics beyond what the schema already provides; baseline 3 applies.

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

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

Specific verb (anhängen) plus resource (Kommentar) plus the two supported targets (Beleg oder Zahlung), and the use case is exemplified ('Hinweis an die Buchhaltung, etwa warum ein Beleg noch offen ist'). No sibling tool competes for this action, so an agent can pick it out unambiguously.

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

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

Gives clear context for when to reach for it (a note to accounting about an open receipt) and states the hard selection rule that exactly one of the two identifiers must be supplied. It does not explicitly route the agent to the search tools for obtaining those IDs in the description text—that routing lives only in the schema—so it falls short of full when/when-not guidance.

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

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

Annotations already define the write/safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=true), but the description adds real value beyond them: it writes to live BuchhaltungsButler accounting data, is reversible only via bb_cost_locations_delete, and its codes become usable in the cost_location fields of posting tools. It does not state what happens if the code is already taken, which keeps this from a 5.

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

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

Front-loads the action and its two constraints, then adds intent, downstream effect, duplicate-check routing, side-effect warning, and undo path — every sentence carries distinct information and none restates structured fields verbatim.

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

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

Output schema covers return values, annotations cover the safety profile, and the description supplies the remaining context an agent needs: side effects on real data, the sibling to consult before creating, and the recovery tool. Complete for a 2-parameter create 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 100% so the formal constraints are already documented, but the description adds semantics: that 'code' is the self-chosen identifier of the cost center and that taken codes can be looked up via bb_cost_locations_search, plus the real-world meaning of 'name'. This goes beyond the schema's examples.

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

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

States a specific verb+resource (legt eine Kostenstelle ... an) plus defining constraints (code max 10 chars, Bezeichnung), and names the sibling tools it relates to (search, delete). An agent can distinguish it from bb_cost_locations_update/search/delete without opening any schema.

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

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

Explicitly gives the intended use case (neue Abteilung oder Projekt, auf das Buchungszeilen verteilt werden), names bb_cost_locations_search for checking taken codes, and names bb_cost_locations_delete as the undo path. When-to-use and alternatives are both stated.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, but the description adds substantial context beyond them: exactly what is removed (the cost center plus its Bezeichnung), that it deletes from the real/production tenant, and that the effect on referencing postings is undocumented and the assignment may be lost. It also prescribes reading affected records and presenting them to the user first.

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?

It is somewhat long, but every sentence carries distinct information (purpose, target scenario, undeclared side effect, impact-check tool, production scope, recommended pre-read) and the core action is front-loaded.

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

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

With an output schema present and only one fully-documented parameter, the description still covers behavior, side effects, production scope, and a pre-deletion workflow. Nothing an agent needs to invoke this safely is missing.

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

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

Schema description coverage is 100% — the single 'code' parameter is fully documented with an example and a lookup hint (bb_cost_locations_search). The description only restates that deletion happens 'über ihren code', adding no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

The description gives a specific verb and resource in German ('Löscht eine Kostenstelle in BuchhaltungsButler über ihren code') and adds the intent behind the operation. An agent can immediately distinguish this from sibling operations like bb_cost_locations_update, _create or _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?

It states a clear usage context ('Gedacht für eine versehentlich angelegte oder nicht mehr benutzte Kostenstelle') and routes the agent to bb_postings_search to inspect affected postings before acting. It does not spell out an explicit 'do not use when' exclusion, but the guidance is concrete.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so this description's job is to add beyond that, and it does: it discloses the returned payload (only code and name, no analysis or sums) and the per-call row cap of 1000. It does not state auth requirements or behavior when code yields no match, so 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?

Front-loaded with the primary purpose, then the workflow, key semantics, return shape and row cap. Each sentence carries information, though restating the return fields is mildly redundant given that an output schema exists.

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

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

Covers purpose, workflow placement, identifier semantics, return scope and pagination limits. With an output schema present, return values need not be spelled out, so nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes further by clarifying the identifier model (no numeric ID, code is the key), which is genuine semantic meaning for the code parameter and not merely a restatement of the schema text.

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

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

States a specific verb (listet) plus resource (Kostenstellen des Mandanten), and adds the exact-code retrieval variant in the same breath. An agent can distinguish this read/lookup tool from the create/delete/update siblings without opening any schema.

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

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

Explicitly names the use case: lookup before a posting line is assigned via cost_location. That is clear context, but it names no alternatives or exclusions (e.g. when to prefer assignment-time resolution instead of a separate 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?

Goes well beyond the annotations: it discloses that bookings referencing the cost center are preserved and re-labelled, that the response does not confirm the new name, that the API returns no previous values, and that the change is irreversible without a prior read. This is exactly the destructive-mutation context the annotations cannot convey.

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

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

Front-loads the core action and each sentence carries operational weight (irreversibility, verification workflow, identifier immutability). Slightly verbose, but nothing is filler.

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

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

An output schema exists, so return values need no explanation, yet the description adds the crucial caveat that the response does not confirm the new name. Combined with the irreversibility warning, an agent has everything needed to call this mutation safely.

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 schema already documents both parameters, including the code's immutability and the lookup hint. The description reinforces that the code stays unchanged but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (überschreibt) and the exact resource scoped (die Bezeichnung einer Kostenstelle), and clarifies that the code/identifier itself is not changed. This lets an agent distinguish it from bb_cost_locations_create/delete/search without opening the schema.

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

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

Gives clear context ('Gedacht für eine berichtigte Bezeichnung') and names the sibling to use for verification (bb_cost_locations_search before and after). It stops short of an explicit when-not-to-use statement, but the intended scenario is unambiguous.

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

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

Annotations cover write/non-idempotent/non-destructive, and the description adds critical extras not in annotations: automatic numbering when postingaccount_number is omitted (and that it is returned), that it writes to real data, and that the API offers no undo endpoint. This materially raises the stakes-awareness beyond structured fields.

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

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

Dense but every sentence earns its place: purpose, use case, numbering behavior, sibling routing, write target, and irreversibility. Front-loaded with the core action and no filler.

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

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

With 13 params, an output schema, and full annotations, the description covers the remaining gaps: auto-numbering, return of the number, sibling alternatives, and irreversibility. Nothing an agent needs to invoke correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value for postingaccount_number by explaining auto-assignment and pointing to bb_creditors_search for checking occupied numbers. The due_in_days caveat about write-only visibility is also covered, though it appears mainly in the schema.

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

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

Specific verb+resource in German: creates a creditor (supplier) account in BuchhaltungsButler. It explicitly distinguishes itself from siblings by naming bb_creditors_create_batch for bulk and bb_debtors_create for customers, making selection unambiguous.

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

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

States the intended use case (new supplier before an incoming invoice is recorded) and names alternatives with their selecting conditions: batch for multiple accounts, bb_debtors_create for customers. Clear when/when-not guidance.

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

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

Adds substantial behavior beyond the annotations: the response is partial-success with an 'errors' array naming each rejected entry, and critically there is no API endpoint to undo the write. This 'no-undo' warning is exactly the kind of risk context annotations (destructiveHint=false, idempotentHint=false) do not convey.

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

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

Front-loaded with the core action, then use case, element shape, response semantics, and irreversibility in tight sentences. No wasted text; each sentence carries distinct, decision-relevant 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?

Covers write target ('echten Buchhaltungsdaten'), partial-success semantics, lack of undo, batch element shape, and intended scenario. Even though an output schema exists, the description adds the failure-mode context an agent needs to invoke this safely.

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 every field, the 1-50 item bounds, and the postingaccount_number behavior. The description only adds that items mirror bb_creditors_create minus email, which is a minor clarification rather than new syntax meaning, so baseline 3 is appropriate.

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

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

States a specific verb+resource (mehrere Kreditorenkonten anlegen) with the batch scope made explicit ('in einem Aufruf'). It names the sibling bb_creditors_create and clarifies the difference (same fields, but without email), so an agent can distinguish the batch from the single-create tool without opening either schema.

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

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

Gives a clear use context ('Gedacht für die Übernahme einer Lieferantenliste') and implicitly routes single-record work to bb_creditors_create by referencing shared fields. It lacks an explicit when-not/alternative statement (e.g. 'use single create for one creditor'), so it stops just short of full guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world). The description adds real behavior: no filtering support, due_in_days is not returned, and the API's 25-row default when no limit is sent. It stops short of describing pagination semantics or the response_format trade-off, which are only in the schema.

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

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

Well front-loaded: purpose first, then scoping exclusions, then the alternative tool, then the behavioral caveats. Slightly dense in the second half but every sentence adds information an agent needs.

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

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

An output schema exists, so return values need not be re-explained. The description covers scope, exclusions, the sibling alternative, and the key API quirk. Only minor gaps remain (pagination chaining between offset/limit is left to the schema).

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

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

Schema coverage is 100% and each parameter (limit, offset, response_format) is documented in detail, including the retry-on-'invalid limit specified' hint. Baseline 3 applies; the description only restates the 25-row default already present in the limit description.

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

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

Specific verb+resource ('listet die Kreditorenkonten ... Lieferantenkonten') with the returned fields named (Kontonummer, Name, Anschrift). It explicitly excludes Sachkonten, Zahlungskonten and Debitoren and points to bb_postingaccounts_search as the sibling for those, so an agent can distinguish it from every near neighbour.

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

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

Gives a concrete when-to-use ('Gedacht zum Nachschlagen, bevor eine Eingangsrechnung einem Lieferanten zugeordnet wird'), explicitly states what it does not cover and where to go instead (bb_postingaccounts_search), and warns about the no-filter limitation.

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 (destructive, idempotent, openWorld), it discloses that partial-update semantics are undocumented and advises sending the full record, warns that it writes to the real tenant, and that the API returns no previous values so the change is irreversible without a prior read. This is exactly the extra context annotations cannot carry.

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

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

Front-loads purpose, then usage, then caveats in a logical order with no filler. It is somewhat dense for a description, but each sentence carries distinct information (scope, identifier, partial-update risk, irreversibility).

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 13-parameter mutation with an output schema already covering returns, the description supplies everything an agent needs: the identifier, the pre-read requirement, partial-update ambiguity, and irreversibility. Nothing material is missing.

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

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

Schema description coverage is 100%, so the schema already documents all 13 fields. The description's identifier note (postingaccount_number is the key and cannot be changed) largely duplicates the schema's own text, so it adds little beyond the baseline.

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

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

States a specific verb and resource (überschreibt die Stammdaten eines Kreditorenkontos) and even scopes the fields touched (Bankverbindung eingeschlossen). An agent can distinguish this mutation from the read sibling bb_creditors_search, which the description names explicitly.

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

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

Gives a concrete usage context ("Gedacht für eine geänderte Anschrift oder IBAN eines Lieferanten") and a prerequisite workflow (read the record first with bb_creditors_search before overwriting). It does not explicitly state when NOT to use it, e.g. routing account creation to bb_creditors_create, so it falls short of a full 5.

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

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

Annotations already declare a non-read-only, non-destructive, non-open write, but the description adds material context beyond them: writes go to real live accounting data, and the API offers no endpoint to undo the operation. It also discloses the auto-numbering side effect and that the assigned number is returned in the response.

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

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

Six tight sentences, each carrying distinct information: purpose, usage context, default behavior, alternatives, write scope, irreversibility. Purpose is front-loaded and nothing is padding.

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 mutation tool with full schema coverage, an output schema, and safety annotations, this description covers everything an agent needs: what it does, when to pick it versus siblings, and the irreversible-write risk. No gap remains for correct invocation.

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

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

Schema description coverage is 100% across all 13 parameters, so the schema already carries parameter meaning and 3 is the baseline. The description's note that omitting postingaccount_number triggers automatic numbering duplicates what the schema's own description says rather than adding new syntax or constraints.

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 ('legt ein Debitorenkonto, also ein Kundenkonto, in BuchhaltungsButler an') and immediately disambiguates the German term. It names the sibling tools it is not (bb_debtors_create_batch, bb_creditors_create), so the agent can select correctly without opening schemas.

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

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

Explicit context for use ('für einen neuen Kunden, bevor ihm eine Ausgangsrechnung zugeordnet wird') plus clear routing to alternatives: batch creation for multiple accounts and bb_creditors_create for suppliers. Both when-to-use and when-to-use-something-else are covered.

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

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

Going well beyond the annotations, it discloses partial-success semantics (an 'errors' array naming rejected entries), that the operation writes to live BuchhaltungsButler accounting data, and that no undo endpoint exists — valuable for a non-idempotent write. However, the partial-success claim sits in tension with the schema's statement that a rejected batch is not partially processed, which weakens the reliability of the behavioral description. The irreversibility note does not contradict destructiveHint=false, since creation is not a destructive operation.

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

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

Front-loaded with purpose before intent, response behavior and risk warnings; no filler sentences. Slightly repetitive because the field-equivalence and batch-size statements reappear in the schema.

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

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

For a batch mutation tool with annotations and an output schema, the description covers the missing pieces an agent needs: intent, partial-failure handling, production data, and irreversibility. It omits any guidance on the partial-vs-all-or-nothing conflict and on retry/rate behavior, so it is strong but not airtight.

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 a single top-level parameter and 100% schema description coverage, the schema already carries the field-by-field semantics, so the baseline is 3. The description's notes ('same fields as bb_debtors_create', 'without email', 50-item cap) are duplicated verbatim inside the schema, adding no meaning beyond what structured data 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?

States a precise verb and resource ('Legt mehrere Debitorenkonten ... an') and adds the batch scope ('in einem Aufruf') plus the intended scenario ('Übernahme einer Kundenliste'). It anchors itself to the sibling bb_debtors_create by declaring identical fields minus email, so an agent can distinguish the single-create tool from this one without opening either schema.

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

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

The intent sentence ('Gedacht für die Übernahme einer Kundenliste') tells an agent clearly when this tool is the right choice, i.e. bulk onboarding of existing customers. It stops short of explicit routing rules or exclusions (e.g. 'use bb_debtors_create for a single debtor'), so it is context-rich but not fully directive.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so the safety profile is covered. The description adds genuinely new behavior: no server-side filtering and a 25-row default when no limit is sent, plus the note that the tool always sends a limit. It stops short of describing pagination totals or response shape, which the output schema carries.

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 that front-load the purpose, then the alternative, then the paging caveat. The 25-row statement duplicates the schema's limit description, which is the only 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?

With an output schema present, rich annotations, and fully documented parameters, the description covers everything an agent still needs to know: scope, exclusion, alternative route, no filtering, and the default page size.

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

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

Schema coverage is 100% and the limit/offset/response_format descriptions are already detailed in the schema, including the 25-row default and the 'invalid limit specified' halving advice. The description's limit remark largely repeats what the schema already says, so it adds little beyond the baseline.

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

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

States a specific verb and resource ('Listet die Debitorenkonten des Mandanten') and enumerates the returned fields (Kontonummer, Name, Kundennummer, Anschrift). It explicitly excludes Sachkonten, Zahlungskonten and Kreditoren and names bb_postingaccounts_search as the sibling for those, so an agent can separate it from the many other *_search 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?

Gives the concrete moment of use ('Nachschlagen, bevor eine Ausgangsrechnung einem Kunden zugeordnet wird') and an explicit an alternative-tool route ('dafür bb_postingaccounts_search'). It also warns that the endpoint has no filter, which is usage-limiting information an agent needs before calling.

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

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

Adds substantial context beyond annotations: warns that an omitted field's behavior is unspecified, advises sending the full record, warns changes hit the live Mandant and are irreversible because previous values are not returned. That irreversibility disclosure is exactly what destructiveHint=true implies but cannot verbalize.

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

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

Front-loads the core action, then routes, then warns about the irreversible write. Sentences are dense and each earns its place, though the passage on postingaccount_number's type split could sit closer to the field definition.

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

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

Covers purpose, identifier, lookup requirement, irreversibility, and the partial-update caveat, which is complete for a destructive mutation with an output schema. The one residual gap — that it does not name bb_debtors_create as the alternative for new accounts — is minor given the identifier-based framing.

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 schema already carries field semantics; baseline would be 3. The description adds two non-obvious facts: postingaccount_number is the immutable identifier, and it must be an integer here whereas create expects a string — a type-mismatch trap worth flagging.

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 (überschreibt) plus resource (Stammdaten eines Debitorenkontos) and enumerates the fields affected (Anschrift, Bankverbindung). Distinguishes from bb_debtors_create by naming the identifier (postingaccount_number) that this tool addresses, which create does 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?

Clearly frames the target scenario (changed address or IBAN) and routes the agent to bb_debtors_search for the prior record. Does not explicitly state when-not to use it vs. bb_debtors_create, but the identifier-based framing makes the boundary inferable.

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

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

With annotations present the bar is lower, and the description still adds substantial context beyond them: the write lands in real BuchhaltungsButler data, there is no API path to read the invoice or its PDF (only the web UI), there is no currency parameter because API invoices are EUR-only, and there is no endpoint to undo the write. The irreversibility warning sits in mild tension with destructiveHint=false, though creating a record is additive rather than a destructive update, so it is complementary rather than contradictory. Auth needs and rate limits are not 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?

Front-loaded correctly: what it creates, then when to use it and which sibling to prefer, then the operational caveats. Dense and mostly waste-free, though the worked example and the sibling detour lengthen the opening considerably and could be trimmed.

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 27-parameter irreversible write with an output schema, the description covers the decisive operational facts: finality trigger, alternatives, no read-back path, EUR-only, no undo. It stops short of documenting failure modes (e.g. duplicate invoicenumber handling) or delivery of the PDF, but the core is sufficient to call the tool correctly.

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

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

Schema coverage is 100%, so the schema already carries the field-level detail (including the item_amount vs item_single_price distinction and the parallel-array conversion). The description still contributes beyond the schema by flagging the absent currency parameter and illustrating a realistic call ('10 Std. Beratung zu 120.00 je Stunde'), which prevents a foreseeable misuse.

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

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

The description states a precise verb and resource ('Erzeugt ... eine endgültige Ausgangsrechnung, eine Gutschrift oder ein Angebot') and immediately qualifies the scope ('endgültig', nummeriert, PDF, Ausgangsbeleg). It explicitly separates itself from the two nearest siblings, so an agent can route without opening any schema.

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

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

It gives an explicit when-to-use trigger ('Zu nehmen, sobald der Vorgang final ist') plus a concrete example, and names both alternatives with the condition that selects them: bb_invoices_create_draft for a draft without numbering, bb_invoices_create_einvoice for an e-invoice with per-position tax type. Nothing is left to inference.

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

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

Goes well beyond the annotations: warns that the response carries only success and message (no id_by_customer, no invoicenumber) and that no API path exists to read the draft later. It also discloses that the endpoint excludes invoicenumber, due_days, and payment_reference, that it writes to real accounting data, and that there is no undo endpoint. This is unusually rich disclosure for a write operation.

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

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

Front-loads what the tool creates and its distinguishing traits before moving to sibling routing and behavioral caveats. The sentences are dense but each carries a specific fact (missing fields, no read path, no undo). Slightly heavy at ~90 words, but no filler.

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

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

Given a 24-parameter write tool with an output schema, the description covers the critical behavioral gaps: what is omitted from the response, what the API cannot do afterward, and how it relates to sibling creation endpoints. The output schema handles return shape, so 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 description coverage is 100% and each field already has a detailed description, including field-name remapping (type → invoice_type), enum semantics, format rules, and DATEV warnings. The tool description itself adds no additional parameter-level information, so baseline 3 applies under high 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 names the verb and resource precisely ('Erzeugt in BuchhaltungsButler einen Rechnungsentwurf') and enumerates distinguishing characteristics: no final number, no PDF, but a visible object. It further separates itself from the sibling tools bb_invoices_create and bb_invoices_create_einvoice by 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?

States explicitly when to use it ('solange der Vorgang noch abgestimmt wird, etwa ein Angebot zur internen Durchsicht') and names both alternatives with their distinct roles. The routing between draft, final invoice, and e-invoice is unambiguous.

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

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

Annotations already flag a non-idempotent, non-read-only write, but the description goes well beyond them: it warns this writes into real BuchhaltungsButler data, that there is no API endpoint to undo it, that there is no API path to read the resulting invoice back (only the web UI), and that the endpoint applies the strictest field validation in the API. This is exactly the operational caveat an agent needs before calling.

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?

Five dense sentences packed into one paragraph, front-loaded with the purpose and the sibling routing before the validation and irreversibility caveats. Slightly long, but each sentence carries distinct information (routing, required-field deltas, no-read path, irreversibility) rather than filler.

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

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

For a 28-parameter, 11-required mutation tool this covers the gaps that matter: it duplicates none of the output schema but supplies the irreversibility, the missing read-back path, and the sibling selection rule. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it calls out which fields become mandatory here (e_invoice_id plus street, zip, city, country, email) and that positions use item_tax_type/item_tax_amount in place of item_vat, an API renaming the schema does not explain. That goes beyond restating the required list.

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 ('Erzeugt ... eine E-Rechnung: endgültig, nummeriert, mit PDF und strukturiertem Datensatz nach EN 16931') and immediately names the two closest siblings (bb_invoices_create for the ordinary invoice, bb_invoices_create_draft for a draft). An agent can distinguish this from every other invoice tool without opening a schema.

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

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

Explicit when-to-use ('Zu nehmen für Empfänger, die eine E-Rechnung verlangen, etwa öffentliche Auftraggeber') and explicit alternatives with the condition that selects each ('bb_invoices_create erzeugt die gewöhnliche Rechnung, bb_invoices_create_draft einen Entwurf'). Nothing is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), yet the description adds non-obvious behavior: a hard cap of 5 API calls, the fact that individual chart-of-accounts entries never come in full because they weigh ~60k tokens, and a bundle.complete flag signalling truncation. These are genuine operational traits an agent could not infer from structured fields.

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

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

Content is dense but front-loaded: the core find-anything capability comes first, then no-query mode, then sibling routing, then limits. Sentences are long and clause-heavy but every one carries distinct information; only slight tightening would be possible.

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

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

With an output schema present, return-value documentation is unnecessary, and the description still flags the bundle.complete completion signal. Together with the API-call ceiling, the token warning, and the no-query behavior, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so the schema already documents areas, query, max_hits and response_format in detail. The description adds little parameter-specific guidance beyond what is in the schema, so the baseline of 3 for high coverage applies.

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

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

Starts with a concrete verb ('Findet') and enumerates the five resource types it can resolve (Zahlungskonto, Sachkonto, Debitor, Kreditor, Kostenstelle), plus the lookup keys (Name oder Nummer). It also states the key differentiator—you don't need to know which list holds the entry—which instantly distinguishes it from the per-entity search tools in the sibling set.

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

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

Explicitly names the five sibling tools it replaces for number lookups (bb_payment_accounts_list, bb_cost_locations_search, bb_postingaccounts_search, bb_debtors_search, bb_creditors_search) and carves out the exception where those singles still win (Adresse und Bankverbindung). It also clarifies when to call it without a query (session start context) versus with one.

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

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

Annotations declare non-read-only, non-idempotent, non-destructive, open-world, but the description adds genuinely new behavioral context: it writes to real BuchhaltungsButler data, the API offers no undo endpoint, and is_revision_safe permanently locks in behavior. That irreversibility disclosure is exactly the kind of context the annotations do not carry.

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

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

Front-loaded with purpose and dense with useful routing and constraint information; every sentence carries content. There is mild redundancy where the postingaccount_number guidance repeats what the schema property description already states.

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 5-parameter mutation tool with an output schema (so return values need no explanation), the description covers purpose, eligibility, cross-parameter constraints, alternatives, and irreversibility. It does not mention permission/auth prerequisites or error behavior when a posting account number is already taken, leaving a small gap.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds a cross-field constraint not in the schema ('Die postingaccount_number muss zur gewählten Art passen') and points to bb_payment_accounts_list for used numbers. It slightly duplicates the schema's own is_revision_safe note, so it is above baseline but not fully additive.

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 ('Legt ein manuell geführtes Zahlungskonto ... an') with concrete examples (Kasse, Kreditkartenkonto) and scopes it to accounts without a bank connection. It also names the sibling it must not be confused with (bb_postingaccounts_create), so an agent can route correctly without opening schemas.

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

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

Explicit when-to-use ('Gedacht für ein Konto ohne Bankanbindung'), explicit when-not ('Ein Aufwands- oder Ertragskonto ist kein Zahlungskonto') with the alternative tool named, plus a pointer to bb_payment_accounts_list for choosing postingaccount_number. Nothing is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description goes well beyond them: it discloses the absence of limit/offset and that all accounts are always returned, plus negative disclosure of fields the endpoint never provides (Kontoart, Kontostand, Währung). The warning that a Sachkontonummer actually designates a Zahlungskonto is high-value guidance that prevents a real mapping error.

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

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

A single front-loaded paragraph that opens with what the tool lists before moving to return shape, downstream mapping, and limitations. Every sentence carries information, though the density (four distinct concerns in one block) makes it slightly harder to scan than a short structured list would 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 an output schema present, return values need no restatement, and annotations cover safety; the description fills the remaining gaps (pagination behavior, missing fields, cross-tool value mapping). For a one-parameter list tool, an agent has everything needed to call it correctly 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?

Schema description coverage is 100% and the single response_format parameter is fully documented in the schema, so the baseline of 3 applies. The description never mentions response_format, adding no meaning beyond the schema, but nothing is left ambiguous either.

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

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

States a specific verb and resource ('Listet die Zahlungskonten des Mandanten') and immediately enumerates the resource scope (Kassen, Bank- und Kreditkartenkonten). It is clearly distinguishable from the sibling bb_payment_accounts_create and from bb_postingaccounts_search, which it explicitly names as a different source.

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

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

Gives an explicit use case ('Gedacht zum Nachschlagen, bevor eine Zahlung oder ein Beleg einem Konto zugeordnet wird') and routes the agent to the correct alternative for a different need ('Kontoart ... steht als subtype in bb_postingaccounts_search'). It also names the downstream consumers of the returned value, so the agent knows exactly when and why to call this tool.

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

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

Annotations already declare readOnly=false, idempotent=false, openWorld=true, destructive=false. The description meaningfully adds that it writes to real accounting data and that the API exposes no endpoint to undo the creation — a genuine irreversibility warning that isn't in 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?

What the tool does is front-loaded, followed by use case, inheritance/lookup requirement, alternatives, and side effects in an efficient sequence. Every sentence carries distinct information with no padding.

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

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

With an output schema present, return values need no explanation. Prerequisites, exclusions, sibling routing and irreversibility are all covered, leaving nothing an agent needs to call this correctly.

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

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

Schema description coverage is 100%, so all three parameters are already documented with examples. The description restates the inheritance-from-parent semantic but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource (legt ein neues Sachkonto im Kontenrahmen des Mandanten an) and explicitly distinguishes this from customer, supplier and payment accounts by naming the sibling tools that handle those cases. An agent can select it without opening any schema.

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

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

Gives an explicit use case (eigenes Aufwandskonto, e.g. 4931 für Softwarelizenzen), names the alternative tools with their conditions (bb_debtors_create, bb_creditors_create, bb_payment_accounts_create), and states the prerequisite of looking up the parent account with bb_postingaccounts_search first.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so safety is covered. The description adds real behavioral value beyond that: the union-of-types structure and that type/subtype are always returned, plus the API's implicit 1000-row default with no documented upper bound. It does not, however, discuss the response_format server-side behavior or pagination edge cases.

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

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

Front-loads what the tool is, then the union caveat, then sibling routing, then scope exclusions. Each sentence carries information, though the routing sentences are dense enough that the paragraph runs long. Still efficient and well-ordered.

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

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

An output schema exists so return values need not be explained, and annotations cover the safety profile. The description fills the remaining gaps: union composition, always-present type/subtype, intended use case, sibling alternatives, and out-of-scope operations. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 8 parameters including limit, offset, order, exclusions and response_format. The description's only parameter-relevant addition is the 1000-row API default, which the schema already partly notes. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Durchsucht den Kontenrahmen des Mandanten') and immediately clarifies the non-obvious scope: the result is a union of Sachkonten, Zahlungskonten, Debitoren and Kreditoren distinguished by type/subtype. This differentiates it cleanly from siblings that an agent might confuse it with.

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

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

Explicit routing: use this to look up a Sachkontonummer before booking; use bb_payment_accounts_list for payment accounts, bb_postingaccounts_create to create an account, and bb_reports_get_ledger for balances/postings. It also states what this tool does NOT do, which is exactly the guidance an agent needs to pick the right 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?

Annotations declare destructiveHint=true and idempotentHint=true, but the description adds crucial context beyond them: existing bookings continue to reference the account and remain unchanged, the API does not return prior values, and the change is irreversible without a prior read. This goes well past the annotation set.

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, then flows through scope, prerequisite, and irreversibility warning. Every sentence carries distinct information, and the ordering is efficient for an agent scanning for pre-flight steps.

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

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

Despite a live-tenant mutation with no rollback and an output schema that only returns the new state, the description covers the missing pieces: read-first requirement, referential behavior of existing postings, and irreversibility. Nothing an agent needs to call this safely is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented with examples ("Softwarelizenzen Cloud 19% USt", "4931"). The description reinforces the immutability of postingaccount_number, but adds no syntax or format detail the schema lacks, so the baseline of 3 applies.

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

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

The description states a precise verb+resource in German ("Überschreibt die Bezeichnung eines Sachkontos") and immediately scopes exactly what changes versus what stays fixed (Nummer, Vorlagekonto, Steuerbehandlung). This lets an agent distinguish it from bb_postingaccounts_create and bb_postingaccounts_search without opening any schema.

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

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

It explicitly names the prerequisite workflow ("Den alten Namen vorher mit bb_postingaccounts_search lesen") and states the tool is intended for a corrected account label, effectively excluding general editing. The condition that selects the read sibling is spelled out.

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

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

Goes well beyond annotations to disclose key traits: it changes only the linkage and not the posting record, creates no posting, requires posting_id_by_customer to point to a free posting or the API rejects with error_code 10, writes to real accounting data, and cannot be undone as no API endpoint exists. Annotations (readOnlyHint=false, idempotentHint=false) are consistent and amplified.

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

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

Front-loads the core action, then scenarios, sibling routing, hard constraint, data impact, and irreversibility. All sentences carry information, but it is dense and could be slightly tightened; still appropriately sized for a destructive, irreversible mutation.

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

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

With an output schema present, return values need not be explained. The description covers the mutation's side effects, precondition (free posting), failure signal (error_code 10), data scope, and irreversibility — everything an agent needs to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning: posting_id_by_customer must reference a free posting and rejection yields error_code 10. The schema already documents how to find free postings and the string-vs-int note, so the description complements rather than duplicates.

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 ('Bindet') and resources ('vorhandenen Beleg an eine vorhandene freie Buchung'), and explicitly distinguishes itself from bb_transactions_assign_receipt by naming that sibling and the condition (Zahlung) under which it applies. An agent can tell this apart from the transaction-assignment sibling without opening schemas.

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

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

Gives explicit when-to-use ('wenn eine freie Buchung nachträglich ihren Beleg bekommen soll'), a concrete trigger scenario ('etwa weil bb_postings_create_free ohne Belegbezug gebucht hat'), and names the alternative tool for the other case ('die Zuordnung eines Belegs zu einer Zahlung leistet stattdessen bb_transactions_assign_receipt').

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 declare destructiveHint=true and non-idempotent, and the description adds meaningfully beyond that: a fixed posting produces an irreversible, permanently visible Stornobuchung whereas a non-fixed one disappears, and the API response does not distinguish the two. It also discloses the split-posting constraint (five lines = five calls, intermediate state is unbalanced) and that data is removed from the real tenant.

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

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

Dense but front-loaded: purpose first, then condition, then effects, then constraints. Minor redundancy in restating the removal target ('die genannte Buchungszeile') after the purpose sentence, but no filler.

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

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

An output schema exists so return values need not be explained, and the description nonetheless flags the one thing the output hides (that it does not tell the caller which of the two effects occurred). With the pre-read requirement, single-line scope, and split warning, an agent has everything needed to call this safely.

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 single parameter is already fully documented, including the fixed=1 vs 0 consequence and the string-vs-integer search-result caveat. The description repeats rather than extends this, so the baseline 3 applies.

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

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

States a specific verb and resource ('Storniert ... eine einzelne Buchungszeile') and immediately scopes it to exactly one line, distinguishing it from the unconfirm siblings by name. An agent can tell what this does and what it does not do without opening the schema.

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

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

Gives an explicit when-to-use rule ('wenn eine festgeschriebene Buchung zu korrigieren ist') and routes the non-fixed case to three named alternatives. It even warns that a fixed line leaves a permanent reversal entry while a non-fixed one vanishes, so the agent knows to pre-read 'fixed' via bb_postings_search before choosing.

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