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

The description goes well beyond the annotations: it explains that a single same-name customer causes an update, multiple matches cause no change, and that email/landline/mobile are gated on an autonomy consent setting. It also clarifies the invoice-dispatch limitation for the stored email. This is exactly the kind of behavioral context annotations cannot express.

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: the first sentence states the core action, the next sentences cover duplicate behavior, and the second paragraph covers consent restrictions. Every sentence carries a distinct constraint; none repeats the schema or annotations.

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, no-output-schema mutation tool, the description is nearly complete: it covers duplicate handling, idempotency expectations, and the critical authorization restriction. The main gaps are that it does not describe the tool's return value/confirmation or define what counts as 'gleichnamig' precisely.

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?

It adds meaning absent from the schema by stating that name alone suffices, grouping 'Firma und Anschrift' as optional, and binding the three contact-number parameters to the autonomy consent. It does not add field-level explanations for ort/plz/strasse, but it compensates for the 67% schema coverage with operational conditions.

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 exact action and object ('Legt einen neuen Kunden an'), and the following sentences clarify that this tool is also an upsert by name. This makes it easy to distinguish from sibling creation/search tools such as angebot_anlegen or kunden_suchen.

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

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

It gives practical usage context: only the name is required, address fields are optional, and contact fields require full autonomy. However, it never explicitly tells an agent when to prefer this over kunden_suchen or another sibling; the routing to alternatives is only implied.

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