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

With no annotations at all, the description carries the full burden and does most of it: it declares read vs write access per operation and warns that delete also destroys the stored object, which is the key destructive side effect. It stops short of stating whether deletion is recoverable or what permission/error conditions apply, so a lone agent still lacks a reversibility guarantee.

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?

Front-loads the resource definition, then presents each operation as a compact clause with its access level and effect, ending with the redirect to the add-path siblings. No filler sentences and every clause carries information an agent needs.

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 five-parameter tool with no output schema and no annotations, it describes the list return shape (filename, title/description/summary, signed download_url), which is the hardest part to infer. The delete path's response and error behavior are left unspecified, a minor gap for a destructive operation.

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 coverage is only 20%, so the description must compensate, and it does for the substantive parameters: op values are explained with their effects, file_id is tied specifically to delete, and project_id is implied by 'a project's raw documents'. The generic plumbing params (_org, _run_id) are not addressed in the description, though _run_id is documented in the schema itself.

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?

States a specific resource (a project's raw documents, clarifying it means PDF/HTML attachments) and enumerates the two supported operations with their distinct effects. The final sentence explicitly routes to the two sibling tools that add files, so an agent can distinguish this tool from adjacent ones without opening a schema.

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?

Gives an explicit decision rule: op=list to read the inventory with download URLs, op=delete + file_id to remove an outdated document. It also names the alternatives for the case this tool does not cover (adding), pointing to oto_import and oto_upload_url with the distinguishing condition 'server can reach' vs 'you push'.

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