dns_create_zone

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

No annotations are present, so the description must carry the full behavioral disclosure burden. It only hints at parameter behavior ('Primary' vs 'Forwarder') and omits side effects, prerequisites, duplicate handling, or confirmation of what 'create' entails. The mutation is implied but not disclosed further.

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 sentences, front-loaded with the core action. The first sentence states the purpose; the second adds critical usage nuance. No filler or repetition.

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 simple create operation with two parameters and no output schema, the description plus schema is nearly sufficient. It explains the main action and clarifies the most important type choice. It could improve by mentioning behavior on duplicate zones or expected response, but overall it covers the essentials for a straightforward tool.

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 descriptions cover both parameters (zone, type) at 100%, so baseline is 3. The description adds value by explaining the intended use of two enum values ('Primary' for local hosting, 'Forwarder' for conditional forwarding), which is beyond the schema's generic 'Zone type' description. It doesn't cover Secondary and Stub, but the additional context is meaningful.

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 'Create a new DNS zone,' a clear, specific verb+resource statement. It distinguishes this creation tool from sibling tools like dns_list_zones, dns_delete_zone, and dns_set_zone_options by focusing solely on the act of creating.

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 guidance on choosing zone types, advising 'Primary' for local record hosting and 'Forwarder' for conditional forwarding. It does not mention when not to use the tool or name alternatives, but for a creation operation the context is clear.

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