host_delete

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

The description explicitly states that the operation is destructive and 'will delete all associated data including history and alerts.' This goes beyond the provided annotations (destructiveHint=true) by detailing the irreversible nature and the extent of data loss, which is crucial for an agent to warn users or confirm before invocation.

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 concise yet comprehensive, covering the action, scope, consequences, and a warning. It is well-structured with a clear first sentence and supporting detail, without unnecessary verbosity.

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 destructive tool with no other annotations beyond destructiveHint, the description adequately warns about data loss. However, it does not mention prerequisites (e.g., permissions) or what the response contains (though an output schema exists). It's solid but could add guidance on required access levels or clarification that deletion is immediate and irreversible.

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?

The schema fully documents the single parameter 'hostids' with a proper description ('List of host IDs to delete'). The tool description expands on the effect of this parameter by explaining that it permanently removes the specified hosts justifications, providing sufficient context for correct parameter usage.

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 action: 'Delete hosts from Zabbix.' It specifies the target resource (hosts) and the operation (delete), which distinguishes it from sibling tools like host_get, host_create, and host_update. The description also notes that it removes one or more hosts, matching the parameter 'hostids' that accepts a list.

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 says it 'permanently removes one or more hosts from Zabbix' and warns 'Use with caution as this is a destructive operation.' This implies it should be used when permanent removal is intended, but it does not explicitly state when to use it over other deletion tools (e.g., item_delete) or provide exclusions. Sibling tools have distinct purposes, but the description alone doesn't guide selection beyond the resource name.

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