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

Even with readOnlyHint=true already covering side-effect safety, the description adds valuable behavioral context: it does not actually send email, omitting the option yields a populated beratung template rather than a bare mailto, and the partner mailbox is not the hardcoded href. These details go beyond annotations and prevent misuse.

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?

Compact and front-loaded: the WHAT sentence is followed only by essential caveats such as the default call behavior, no-send guarantee, and partner mailbox location. Every sentence carries a distinct fact with 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?

For a tool with zero required parameters, a fully described enum, an output schema, and a readOnly annotation, the description covers invocation, default behavior, side-effect boundary, and the likely partner-mailbox confusion. Nothing needed for correct invocation 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?

The single optional enum is fully described in the schema, so the baseline is 3. The description adds useful business meaning by tying option to a contactOption of one of the 10 end-invoices, cylinder_mount, or beratung and reaffirms the omit-default. However, the mapping leaves three enum values (zugefallen, abgeschlossen, zylinder) unmentioned, so it is not exhaustive.

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

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

The description opens with a specific WHAT: it produces a mailto:info@ikeytz.com link using the same subject+body prefab as compose_whatsapp. This names the exact target resource and output channel, and clearly distinguishes it from the compose_tel_* and compose_whatsapp siblings.

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 concrete call guidance ({} maps to the beratung template, not an empty mailbox), states that email is not sent, and redirects partner-mailbox needs to get_partner_info.partnerEmail. It does not explicitly spell out when to choose this over the WhatsApp or phone compose tools, but the exclusions and references make selection fairly clear.

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