Verify DNS zone

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

Adds a great deal beyond the annotations: the dns:write scope requirement, the meaning of verificationMissing with its checks/next_step payload, the add_txt vs add_txt_at_previous_provider vs contact_support decision, and the explicit note that a 503 lookupUnavailable is a transient failure to retry rather than a missing record. It also clarifies the zone survives while pointed at VPSnet, tempering the raw destructiveHint.

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?

Content-rich and the goal (check TXT, publish on match) is front-loaded before the edge cases. It is dense with nested parentheses and em-dashes, which slightly hurts scannability, but almost every clause delivers distinct, actionable information.

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?

With no output schema, the description does the heavy lifting for returns and covers the refusal shape (verification.checks, verification.next_step) and the 503 case thoroughly. It is a bit thinner on the success return, but an agent knows how to invoke it and how to interpret the notable outcomes.

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 100% and there is a single well-documented zone_id parameter, so the schema already carries the semantics. The description references the zone but adds no new detail (syntax, format, constraints) about the parameter itself, so the baseline 3 applies.

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+resource (verify/publish the DNS zone) and precisely what is checked: the ownership TXT value at _vpsnet-dns.<zone>. It also distinguishes the verification path from sibling operations like reapply_dns_zone or reissue_dns_zone_verification by explaining the check-then-publish behavior.

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 strong context for when to use it (ownership verification before the zone serves traffic, plus the key insight that a domain already delegated to ns1/ns2.vpsnet.com must be verified at the previous provider). However it never routes the agent explicitly against siblings such as reissue_dns_zone_verification, so the alternative-selection guidance is implied rather than stated.

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