provision_host

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

The description adds significant context beyond annotations. It discloses that dry_run=True by default (shows without creating) and how to execute. It explains the atomicity difference between auto_dns=True (records created atomically) and False (separate steps). This is valuable behavioral insight, especially given the openWorldHint annotation which is vague.

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 longer than average but every part serves a purpose: intro, usage directive, important notes, args, return, and examples. It uses clear section breaks and bullets, making it easy to scan. No redundant filler.

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 the tool's complexity (9 parameters, optional behavior, multiple resources affected), the description is complete. It covers purpose, usage, parameter details, return value, and provides three examples. The output schema exists, so the return description is sufficient. No gaps identified.

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?

With 0% schema description coverage, the description fully compensates by providing an 'Args:' section that explains every parameter, including conditions (e.g., subnet required when multiple subnets exist and no IP specified; view required when zone exists in multiple views). It gives examples and types, making the parameter semantics crystal clear.

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 the tool's purpose: 'Provision a complete host in one step: creates IPAM host + IP + optional DNS A/PTR records.' It uses a specific verb (provision) and resource (host), and explicitly distinguishes from siblings by directing DNS-only changes to provision_dns() and removal to decommission_host().

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?

Provides explicit when-to-use guidance: 'USE THIS when adding a new host to the network.' Names alternatives: 'For DNS-only changes use provision_dns(). To remove a host use decommission_host().' Also explains dry_run default and instructs to ask the user about auto_dns, giving clear decision points.

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