delete_submission_files

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description adds extra context: it only applies to 'editable' submissions and requires a confirmation token, which aligns with the annotation. It does not contradict any annotations. It also implies that the operation is not reversible (all files deleted), which is useful beyond the annotations.

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, compact sentence that leads with the action and resource, then adds the condition. Every word earns its place; there is no fluff or redundancy.

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 states the key condition ('editable') and the need for confirmation, but it does not mention how to obtain the confirmation token, what happens to the submission after file deletion, or any side effects. Given there is no output schema and the tool is destructive, an agent would benefit from knowing the token source and the post-deletion state. It is adequate but incomplete.

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 explain the parameters. It only alludes to confirmation via 'tras confirmación' but does not explicitly describe what assignment_id or confirmation_token mean, or how to obtain the token. There is no mention that confirmation_token is required for safety or that it comes from a preview call. The description fails to compensate for the lack of schema descriptions.

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 (deletes all files) and the resource (editable submission), and qualifies it with 'tras confirmación' (after confirmation). It differentiates from siblings like remove_submission (which removes the whole submission) and preview_delete_submission_files (which is likely a preview only). The purpose is unambiguous and specific.

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 that this is the confirmed deletion step (after a preview) but does not explicitly state when to use it versus preview_delete_submission_files or remove_submission. There is no explicit reference to the preview tool or any conditions like 'use this only after previewing'. The guidance is implicit rather than explicit.

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