snaphost_delete

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Delete' implies destructive behavior, which the agent can infer, but the description doesn't state reversibility, permission requirements, what happens to associated data/logs, whether the action is idempotent, or confirmation of successful deletion. For a destructive operation with zero annotation coverage, this is thin.

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 a single, efficient sentence with no filler or redundancy. The phrase 'frees its URL' adds a useful clarifying consequence in parens. It's appropriately sized for a simple one-parameter tool, though it could arguably add one clause about behavior without hurting conciseness.

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?

This is a destructive operation with no annotations, no output schema, and 0% schema coverage. The description tells the agent the what (stop and delete) but omits critical operational details: whether deletion can be undone, how to confirm success, what errors to expect (deploy not found, already deleted), and side effects on associated resources. For a deletion tool, this is meaningfully under-specified.

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 schema description coverage at 0%, the description does nothing to clarify the deploy_id parameter. However, there is only one parameter and the name 'deploy_id' plus the schema's uuid format make its purpose reasonably self-evident. The description provides no additional semantic meaning (such as where to find the ID, format expectations, or validation rules) beyond what the schema gives.

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 uses a specific verb-resource structure: 'Stop and delete a Snaphost deploy (frees its URL).' It clearly names the resource (deploy) and the actions (stop and delete), plus the consequence (frees URL). This distinguishes it from siblings like snaphost_deploy, snaphost_logs, and snaphost_status without being tautological.

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 states the action but gives no guidance on when to use it vs alternatives. It doesn't mention prerequisites (e.g., deploy must exist, must be in a certain state), whether it works on active vs already-deleted deploys, or any exclusions. It only explains what happens (frees URL) but not when or when-not to use it.

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