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

The annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely non-obvious behavior on top: a 2 MiB maximum, dual return encodings (base64 vs UTF-8 text), an authorization constraint, and the fact that org-admin MCP approval settings may gate the call while business workflow approvals always apply.

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?

Three sentences, all short, but the opening clause is generic filler that carries no discriminating information. The substantive content (encoding, size cap, approvals) is packed into the latter half rather than front-loaded, so the most useful facts arrive after the reader has already skimmed the boilerplate.

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?

An output schema exists, so return-shape explanation is not owed. Given a single-parameter read tool with full annotation coverage, the description supplies the remaining decision-relevant facts: size ceiling, encoding behavior, and approval gating. Only the provenance of documentId and the failure mode for oversized files are left unstated.

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% – documentId carries only a uuid format and pattern, with no prose. The description partially compensates by framing the input as a change_request document ('authorized change_request file bytes'), implying the ID must be scoped to a change request, but it never explicitly maps documentId to that resource or says where to obtain one.

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 states a specific verb and resource: read a change_request document's file bytes, returned as base64 or as UTF-8 text for text files. That distinguishes it from the write-side siblings (update_change_request, delete_change_request_document) and from get_change_request, though it never names the parallel read_project_document / read_site_document family it could be confused with.

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 only usage lead-in is boilerplate: 'Use this when working with RetailHardHat documents records in the connected organization,' which would apply equally to every document tool in the list. There is no explicit when-to-use, no exclusion against the other read_*_document tools, and no statement that a documentId must first come from list_change_request_documents.

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