Delete item

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

The annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds valuable behavioral context beyond that: it discloses the confirmation_required behavior and guides the agent on how to handle it, including referencing the 'note' field. This is useful, even though 'note' is not defined in the schema.

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 brief, two sentences, and front-loaded with the primary purpose. The second sentence is somewhat dense but still focused. No excessive words, though the wording could be clearer about the 'note' reference.

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 the tool has 6 parameters and an output schema, the description is moderately complete. It explains the confirmation flow, which is important for a destructive operation, but it omits details about other parameters and edge cases. The output schema exists, so return values are not required, but the description could be more thorough about the delete process.

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 description coverage is only 17%, so the description must compensate for the underdocumented parameters. It adds some meaning to request_state (required for confirmation flow) but does not explain actor, expected_version, require_confirmation, or the idempotency key usage beyond what the schema already says. The reference to 'note' is confusing because it is not a parameter.

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 and resource: "Delete an item permanently." It distinguishes from sibling tools like data_add_item, data_update_item, and data_move_item by specifying the permanent deletion operation.

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 provides clear usage context when it explains the confirmation_required flow: show the note and resend with request_state. However, it does not explicitly discuss when to use it versus alternatives or exclusions, though that is somewhat implicit given the tool's name.

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