delete_project

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

With no annotations provided, the description carries the full behavioral disclosure burden. It does well by explicitly stating that deletion is not immediate, that the action is queued for human confirmation, and that the flags only describe what a confirmed action will remove. It does not cover permissions, idempotency, or post-confirmation behavior, but the most critical non-obvious behavior is clearly disclosed.

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 compact, front-loaded with the core action, and each sentence adds value: the queue behavior, the non-immediate nature, the purpose of flags, and the inspection workflow. There is no filler or redundant restatement of the tool name.

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 deletion-queueing tool with an output schema available, the description is largely complete: it states the action, the confirmation step, and how to inspect pending requests. The main gap is the lack of per-flag parameter explanation, which is important for correct invocation, but the overall workflow context is strong enough to make the tool usable.

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 references 'flags' generically but never explains what delete_remote or delete_progress actually control, nor does it describe the purpose of reason. The parameter names and defaults offer some hints, but an agent cannot reliably understand the semantics of each flag from the description alone.

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+resource+context: 'Queue project deletion for human confirmation in /ui.' This clearly distinguishes it from direct or immediate project actions like resolve_project or rename_projectchers. The added detail that nothing is deleted immediately further sharpens the intended action.

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 context about when to use this tool: to queue a deletion that requires human confirmation. It also routes the agent to list_pending_actions for inspecting the queued request before confirmation. However, it does not explicitly state when not to use this tool or mention alternatives for direct deletion, so it misses the full 5.

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