create_dns_policy

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

With no annotations to carry the safety profile, the description discloses local validation, ValueError behavior naming missing fields, the controller's first validation of the type discriminator, and a verified live failure mode for an empty body. This is considerably more behavioral detail than a bare 'create' label would provide.

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 front-loaded with the purpose, then organized into parameter semantics, validation behavior, and policy guidance. Every detail, including the verified empty-body rejection message, earns its place and no filler is present.

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 an opaque policy object with no annotations and no request-schema descriptions, the description supplies host/site formats, the required type discriminator, validation ordering, and a concrete strategy for discovering the full request shape. Because an output schema exists, not detailing the return value is acceptable.

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 0%, so the description fully compensates: host accepts a console name, ID, or composite ID in MAC:numericId format, site accepts a name or ID, and policy requires a type discriminator plus type-specific fields. It even suggests consulting get_dns_policy for the exact policy shape, which is essential because the schema leaves the policy object unrestricted.

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 opening sentence, 'Create a new DNS policy on a site,' states a specific verb, resource, and scope. It is immediately distinct from sibling operations such as list_dns_policies, get_dns_policy, update_dns_policy, and delete_dns_policy.

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 gives clear context for how to use the tool, such as including name and network scope for a typical policy and reading an existing policy via get_dns_policy to confirm the exact shape. It does not explicitly state when not to use it, though no close alternative create operation exists among the siblings.

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