delete_intake_work_item

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

With no annotations, the description carries the full burden. It provides one useful behavioral nuance (use the issue field, not the intake work item ID) but does not disclose whether deletion is permanent, side effects, permission requirements, or error behavior. Additionally, it mentions workspace_slug as an argument, which is not present in the schema, creating inconsistency and reducing trust.

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 with a single action sentence followed by an args list. It is front-loaded with the purpose. The inclusion of workspace_slug is an error, but structurally it is efficient and not verbose.

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?

The description explains a key ID nuance but omits essential context for a delete operation: no mention of permanence, return value, error conditions, or the relationship between intake work items and work items. The workspace_slug mismatch further detracts from completeness. No output schema is provided, so the description should have covered more.

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 0%, so the description must compensate. It adds crucial meaning for work_item_id (use the issue field) and identifies project_id as a UUID, but it also lists workspace_slug which is not in the schema. This phantom parameter undermines the clarity and reliability of the parameter documentation.

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 'Delete an intake work item by work item ID' with a specific verb and resource. This distinguishes it from siblings like delete_work_item and delete_work_item_attachment. The additional note about using the issue field clarifies the target without obscuring the overall purpose.

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 implies the tool is used for deleting intake work items, which is enough to differentiate from other delete tools. However, it does not explicitly state when to use this versus alternatives like delete_work_item or provide exclusions or prerequisites. The parameter guidance about the issue field is a form of usage context but does not address tool selection.

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