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

Annotations already provide destructiveHint=true, so the agent knows it's destructive. The description adds valuable behavioral detail beyond that: it explains cascading effects (deleting main code file removes css/tests; aux file only clears that part). This is significant context that annotations don't cover. It does not mention permissions or reversibility, but given destructiveHint is explicit, this is adequate. No contradiction found.

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 clear sentences with no filler. The critical nuance (cascading deletion) is front-loaded after the main verb. Every sentence adds value; no redundancy or irrelevant details.

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 destructive delete tool, the description covers the key side effects (cascading behavior) that an agent must know to avoid accidental harm. It does not explain return values or error conditions, but since there is no output schema and the tool is destructive, the pragmatic aspects are well covered. The main gap is parameter semantics (especially expected_version), but overall it's sufficient for safe invocation.

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 has 0% description coverage, meaning the description must compensate for parameters. The description mentions 'project file' and distinguishes between main and aux files, which maps partially to the 'path' parameter. However, it does not explain 'expected_version' (likely for optimistic concurrency) or 'projectId' purpose, which are not obvious. Since parameters are few (3) and two are required, the baseline is 3; description provides some but not full compensation.

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 tool deletes a project file and specifies a verb-resource pair, distinguishing it from siblings like copy_file, rename_file, and edit_file. It also covers a key aspect: deleting an item's main code file removes the whole item; this adds a specific behavioral nuance that differentiates it from generic deletion. However, it doesn't explicitly name alternative tools (e.g., 'to remove dependencies use remove_dependency'), so it's slightly below 5.

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 explains when the tool is appropriate: deleting files, and crucially, clarifies the consequences for main vs. aux files (removing whole item vs. part). This context is useful for deciding whether to delete a file versus editing it or using a different tool. However, it does not explicitly state when NOT to use it (e.g., when the file is a dependency, use remove_dependency) or list alternatives, so it's not a 5.

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