Delete instances

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

Annotations already mark the tool as destructive and non-idempotent that the description reinforces by saying 'Destroys instances and everything inside them.' Beyond that, the description adds crucial behavioral details: it is undoable, it returns a descendant count, services are refused, and paths shift after deletion. This goes well beyond the annotation hints. Slight deduction because it doesn't mention authorization or rate limits, but those are not expected for this tool type.

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 and front-loaded: the first sentence captures the primary purpose)Skip subsequent sentences add exactly the details an agent needs (consequences, constraints, and pre/post-recommendations) without fluff. Each sentence earns its place, and the structure flows from the what to the how to the caveats.

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 there is no output schema, the description compensates by telling the agent what to expect in the response (descendant count). It also covers the major edge cases (services, path invalidation). It doesn't specify the exact format of the response or error cases, but for a destructive tool this is sufficient. A slight extra note about what happens on invalid paths (e.g., not found) would be helpful, but overall it's complete enough for an agent to use it correctly.

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 already covers both parameters (paths and studioId) fully (100% coverage), so the baseline is 3. The description adds value by warning that paths are volatile and must be re-read before a second delete, and that services are refused. That's behavioral context on the 'paths' parameter beyond the schema's type/item description, making it more useful for correct invocation.

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 opens with a specific verb and resource: 'Destroys instances' as one undoable step GOVERNED by one verb. It clearly distinguishes itself from the many sibling tools (create, modify, move, etc.) by focusing on destruction and by noting what it does NOT do (services cannot be deleted). Any agent can tell this is the delete operation without reading the schema.

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 concrete usage guidance: it tells the agent to check the response's descendant count, to avoid deleting services, and to re-fetch paths from find/tree after a deletion because paths shift. This substantially helps the agent sequence operations. It doesn't explicitly say when NOT to use this tool relative to alternatives (e.g., vs. move or modify), but it does give clear operational guidance for correct use, so it earns above average.

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