delete_shape

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

With no annotations provided, the description carries the full burden of disclosure. It does not mention that the deletion is permanent, whether any dependent elements are affected, or what happens if the shape_id does not exist. 'Delete' implies mutation but lacks critical side-effect disclosure.

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, concise sentence that directly states the operation. Every word is necessary, and there is no repetition of schema or annotation information. It is appropriately minimal for a simple delete operation.

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?

Despite low complexity and an output schema, the description omits important behavioral context for a destructive operation. It does not note irreversibility, error behavior, or any prerequisites. A delete tool with no annotations should provide at least a caution or a note on effects, which is missing.

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 input schema has 0% description coverage and only defines shape_id as a string. The description's 'by id' adds minimal value because the parameter name already indicates it is an identifier. No additional details about format, scope, or required context are provided.

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) and the resource (shape) with a specific identifier ('by id'). It unambiguously distinguishes itself from sibling tools like list_shapes or find_shape, as it is the only tool that removes a shape.

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 does not provide any when-to-use guidance beyond the obvious purpose. It does not mention alternatives, prerequisites (e.g., whether the shape must exist), or when not to use this tool. The usage is implied by the action verb, but no explicit contextual guidance is given.

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