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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new traits: the exact byte delta from the uploaded file (the single script tag), no browser or login required, not_found for other workspaces, and truncation behavior that reports full character count. This is well beyond what structured fields convey.

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 what is returned and why it matters, then layers defaults, exclusions, and error/truncation behavior. A few clauses are wordy ('no browser, no screenshot, no human login, and no need to hand the link to the user'), but nearly every sentence carries operational value.

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?

There is no output schema, yet the description discloses the return shape (body bytes, truncation with full character count), error cases, and unsupported content types. Nothing an agent needs to call this correctly is missing.

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 50% (version_id has no description), and the description compensates: it explains the default entry-file behavior, the package-relative path semantics, and supported text extensions for `file`. It adds real meaning for both params but stops short of full syntax detail.

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+resource ('read back the rendered body of a version') and immediately scopes it as the reader-visible bytes, which separates it from get_version (metadata/artifacts) and preview_version. An agent can tell exactly what this returns 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 the motivating use case ('confirms for itself that what went live is what it made') and routes to alternatives: get_version artifacts to list files/entry, preview_url or get_version page count for PDF/PPTX. Explicit exclusions are stated (PDF/PPTX, still-uploading versions, cross-workspace not_found).

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