Delete a library item and its stored file (204)

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is largely covered. The description nevertheless adds material context beyond them: the 204 response, the fact that this is a write gated behind confirm, and critically that there is no server-side dry run, meaning the confirm gate is the only safeguard.

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?

Two short sentences, front-loaded with the action and the confirm requirement, with no filler. The stacked parentheticals '(204) (DELETE /v1/creative-library/{id})' are slightly cluttered but each fragment carries distinct information.

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 three-parameter destructive tool with no output schema, the definition covers the essentials: what is destroyed (item plus stored file), the success status (204), and the client-side gating. It omits whether deletion is reversible and what errors occur when the ID is missing or referenced elsewhere, which keeps it short of a 5.

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?

Schema coverage is 67%: confirm and idempotencyKey are documented in the schema, while id has no description in either place. The description adds the confirm gating semantics but says nothing about what `id` refers to or its format, so it does not compensate for the remaining coverage gap. Baseline 3 is appropriate when the schema carries most of the load.

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?

States a specific verb+resource ('Delete a library item and its stored file') and disambiguates scope by noting the stored file is removed too, with the concrete endpoint DELETE /v1/creative-library/{id}. It is clearly distinct from read siblings like creativeLibrary_get, creativeLibrary_file, and creativeLibrary_content, though it does not explicitly contrast itself with any sibling.

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?

Implies the two-step usage pattern via 'WRITE: not executed unless confirm: true', so an agent learns the tool will not act without a confirmation parameter. It never states when to use this versus another route (e.g. unpublishing vs deleting) or any prerequisites/permissions required.

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