delete_namespace

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

Beyond the destructiveHint and readOnlyHint annotations, the description reveals critical behaviors: the tool is refused while TKC clusters exist, it performs a dry run by default unless dry_run=False and confirmed=True, it is irreversible, and it returns either a preview or a deletion confirmation. This rich detail goes far 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 structured with a concise summary, a safety/behavior section, and an Args list. Every sentence provides unique and essential information—no filler. Although it is longer than a simple one-liner, it packs crucial details in an organized, skimmable way.

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 output schema, the description is remarkably complete: it states the outcome, the safety refusal condition, the required prerequisite steps, the alternative tool, the dry-run default, and the meanings of all parameters. There is no significant missing context that a caller would need.

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 manually explains all four parameters: name (discover via list_namespaces), confirmed (must be True to proceed), dry_run (preview only, default True), and target (vCenter in config.yaml, default if omitted). This fully compensates for the schema's lack of descriptions.

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 a vSphere Namespace and everything inside it.' It uses a specific verb and resource, and distinguishes itself from update_namespace by noting it is the irreversible deletion option. This fully differentiates it from sibling tools.

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 explicit when-to-use and when-to-avoid guidance: it says prefer update_namespace for quota changes only, and explains that deletion is refused while TKC clusters exist, directing the user to list_tkc_clusters and delete_tkc_cluster first. It also mentions discovering names via list_namespaces, making usage conditions clear.

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