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

Annotations only give the generic hint set (not read-only, not idempotent, not destructive). The description supplies the operationally critical facts: the upload_url accepts exactly one HTTPS PUT of exactly the declared bytes, carries its own single-use credential so no Authorization header is required, and expires after ten minutes, and that the server never reads a local path.

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?

Four sentences, each load-bearing, with the reservation purpose front-loaded and the return/credential mechanics following. Dense but not padded; a little more length than strictly required for the credential and expiry details, which are nonetheless valuable.

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?

Given an output schema exists, the description correctly does not restate every return field, yet it still explains the two returned URLs and required_headers in behavioral terms. For a five-parameter, non-idempotent mutation tool this leaves no material gap for an agent to call it correctly.

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 carry the burden, and it does: it explains that action identifies the target that takes a file, and that the declared mime_type, byte_size and sha256 are checked against that action's limits. filename and the exact-match PUT semantics are covered too, though format details for each field are left to the schema patterns.

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 and resource: it reserves a one-time upload slot for a named action, gated on type/size/SHA-256 validation. That framing separates it from sibling tools like xora_upload_from_url, xora_upload_request and xora_upload_status without the reader needing to open any 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 clear context for when to call it (an action that takes a file, where the caller holds the bytes) and names concrete alternatives: owner_upload_url for handing the choice to the owner, and passing an image to the action directly by address or base64 for social posts. It stops short of naming sibling tools explicitly, but the conditions for choosing each route are stated.

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