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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, but the description adds two things not in structured data: it never returns an upload link or token, and it can report an intermediate 'still reading' state that the agent should surface and then re-check. Error cases (expired token, unknown requestId, how long to wait) are not covered.

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-loaded with the purpose, then the parameter rules, then the response handling, then the self-only constraint — a sensible order with no filler. Some sentences are dense and pack two ideas (e.g., the still-reading instruction), but every sentence carries operational weight.

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?

With no output schema, the description compensates by naming the two observable outcomes (arrived vs. still reading) and one guaranteed non-return (no link/token), plus the self-only scope. It falls short of covering failure modes and expected polling latency, which an agent may need in practice.

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 100%, so the baseline is 3, but the description adds the selection logic the schema only implies: requestId is the normal path when the upload tools are mounted, token is the fallback for a direct dropUrl call. Both parameters are optional, and the description clarifies when each is appropriate.

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 verb (check), resource (a file deposit), and scope (THEIR OWN X1 documents), which separates it from listing tools like get_vault_documents or search_my_documents. It also names the upstream tools whose requestId it consumes, so an agent knows exactly where this sits in the approval-to-deposit flow.

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 explicit conditional invocation rules: pass requestId when request_vault_upload_link or create_my_vault_upload are mounted (the usual path), pass token only when a direct call returned a dropUrl. It also prescribes the follow-up behavior in each outcome, which resolves the ambiguity about whether to answer the user or keep waiting.

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