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

Goes well beyond the annotations: the server performs an optimistic-concurrency check against "alt" and writes nothing if the record changed or was deleted, the update is implemented as delete+recreate so record_id changes, and protected records (MX, SPF, DKIM, DMARC, apex/www A/AAAA, MX targets) require a bestaetigung. It also names the concrete blast radius (Mailzustellung, Erreichbarkeit der Website) and the confirmation duty toward the customer.

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 and record types, then the constraints and workflow; nearly every sentence carries a constraint an agent needs. It is a single dense paragraph without line breaks for the workflow, confirmation and warning segments, which hurts scannability for a 16-parameter tool.

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 16-parameter, nested-object mutation with no output schema, the description supplies everything an agent needs: the precondition (fresh read), the idempotency/verification model, the postcondition (new record_id, refetch), the protected-record confirmation gate, and the risk statement. No behavioral gap is left to the schema or annotations.

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 semantics on top: "alt" must be the record exactly as delivered (the schema says this too, but the description ties it to the concurrency check), and the new values must include ALL fields of the new record, not just the changed ones — a non-obvious constraint. The type-specific "opt" encoding is restated from the schema rather than extended.

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 (ändert EINEN bestehenden DNS-Eintrag) and enumerates the seven supported record types plus concrete examples (IP einer Website, MX-Ziel, SPF-Wert, SRV-Port). It explicitly contrasts itself with add_dns_record and delete_dns_record, so an agent can distinguish it from siblings 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?

Gives explicit when-not conditions (type cannot be changed → use delete_dns_record + add_dns_record; NS/SOA never editable) and a numbered workflow: fetch fresh via get_dns_records, pass record_id and previous values as "alt", supply all new fields like add_dns_record, then refetch. Alternatives and prerequisites are named rather than implied.

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