Debitorenkonten im Stapel anlegen

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.