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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the write/duplicate-risk profile is covered. The description adds one genuinely behavioral fact beyond that: the document receives its number immediately on creation. It says nothing about validation failures, address completeness requirements, or whether an existing draft can be reused.

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, front-loaded with the operation and its main routing decision; almost no filler. Minor waste in echoing the title verbatim at the start of the sentence.

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 creator with no output schema and no annotations on permissions, the description covers the primary creation paths and the numbering result but says nothing about minimum viable input (can it be called with zero parameters?), how country/address fields interact, or what the call returns. Adequate but with 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?

With 15 parameters and only 60% schema description coverage, the description carries some of the burden and does highlight the decisive ones: billing_document_id, customer_id, customer_name, address fields and lines. However, it largely restates the schema's own billing_document_id text (including field precedence) rather than adding new meaning, and leaves the remaining address parameters undocumented in both places.

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 operation and its result: 'Lieferschein anlegen; bekommt sofort seine Nummer' – a specific verb plus resource, plus the notable outcome that the document is numbered immediately. It is clear what is produced, but it does not distinguish this tool from siblings like create_document or create_credit_note 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?

It gives explicit path guidance: the easiest route is billing_document_id (pulling line items and address from an invoice/order), otherwise customer_id or customer_name together with an address and lines. That is real when-to-do-what guidance. It stops short of stating exclusions, prerequisites, or when to prefer a sibling tool.

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