update_dns_record

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description discloses two genuinely non-obvious behaviors: an upsert fallback when the id does not exist, and that the updated record receives a NEW id that must be reused for later changes. It doesn't address permissions/auth scope or whether replacement is recoverable. Note a mild tension: the new-id-on-update behavior means a repeated call with the same id would insert again, which sits awkwardly with idempotentHint=true, though the description does not directly assert idempotency.

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 short sentences plus a follow-up note; the purpose and the upsert caveat are front-loaded with no filler. The indented line break around the new-id note is slightly awkward but not wasteful.

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?

An output schema exists, so return values need not be explained, and annotations carry the safety profile. The description supplies the odd upsert and id-change semantics, but omits permission/authentication requirements and any propagation caveat for a mutation tool with an openWorldHint.

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 description coverage is 83%, so the schema already documents id, ttl, name, value and domain; baseline is 3. The description's only added semantic is "Every field is required," which is a whole-record-replacement hint but is imprecise since ttl has a default and only 5 of 6 fields are in the required list.

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 ("Replace an existing DNS record") and is immediately distinguishable from the sibling tools add_dns_record and delete_dns_record. The scope of the operation is clear without opening the 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?

It conveys implied usage context (call it when a record already exists and must be replaced, passing all fields) and warns that a missing id causes an add, but it never explicitly says when to prefer add_dns_record over this tool or vice versa. Usage must be inferred from the verb choice rather than stated.

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