tm_verify_domain_dns

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

Annotations already provide idempotentHint: true and destructiveHint: true. The description adds valuable behavioral details: the 400 error on miss (deliberate for fast failure), response shape with verified=true, verifiedAt, verificationMethod='DNS', and specific code references. This goes beyond annotations.

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 well-structured with clear sections and bullet points. It is longer than necessary but each sentence adds value, including error handling details and response shape. Could be slightly more concise, but effective.

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?

Given one parameter, no output schema, and annotations, the description covers the verification process, error conditions, response details, and integration with other tools (tm_add_domain, tm_list_domains). It is fully complete for an AI agent to use correctly.

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 0%, so description must compensate. It explains the domain must be previously added via tm_add_domain and implies domain_id is the identifier, but does not explicitly describe the parameter's meaning or constraints beyond that. It adds marginal value over the schema's 'integer' type.

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 clearly states it 'Run the DNS-TXT verification check on a previously-added domain.' It uses specific verb ('verify') and resource ('domain'), and explicitly distinguishes from sibling tm_verify_domain_http by specifying DNS method.

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?

The description provides explicit context: run after tm_add_domain, and pair with tm_list_domains to confirm. It explains the 400 error behavior for CI flows. However, it does not explicitly state when not to use this tool or compare with alternatives beyond naming tm_verify_domain_http as a sibling.

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