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

Goes well beyond the annotations: it discloses the 30-minute fileRef lifetime and deletion, that AI-mode PDF parsing costs ~5s per page and counts as an AI request, that pdfBackend must be repeated across cursor calls, and that all parts must be read before answering about the whole document. These are exactly the non-obvious behavioral costs and constraints an agent needs, and they are consistent with readOnlyHint/openWorldHint/idempotentHint=false.

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 organized into labeled sections (input routes, outputFormat, pagination, pdfBackend, how to send a file) with indented bullets that make scanning easy. It is longer than most descriptions, but nearly every line conveys a distinct operational rule; the repetition of fileRef/filepath in the cursor paragraph is minor.

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 12-parameter, branching tool with no output schema, the description covers input selection, output format semantics, pagination protocol, cost/speed implications, and cross-tool routing. The only real gaps are the auxiliary parameters (apiKey, requestId, contentEncoding) and error-shape detail, which are secondary given the tool's complexity is otherwise fully addressed.

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?

With 0% schema description coverage the description carries the load well, explaining fileRef format, filepath accepted values, content+filename extension-driven parsing, outputFormat options, cursor usage, maxChars default and range, and pdfBackend values. However apiKey, requestId, and contentEncoding are never mentioned, so three of twelve parameters remain undocumented anywhere.

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?

Names a specific verb and resource ('parse a document') and enumerates the concrete outputs (blocks, markdown, html, a2ui, summary), which lets an agent distinguish it from mcpConvert and mcpFormats named in the sibling list. An agent knows exactly what it gets back without opening the 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?

Explicitly says 'Give the document ONE way' and then routes each situation: fileRef for already-uploaded files, file for ChatGPT attachments, filepath for public URLs or sample ids, content+filename for short text, plus a decision tree pointing to createUpload or uploadDocument when the file isn't reachable otherwise. It also advises calling with summary first for large documents and warns never to substitute your own parsing, leaving almost nothing to inference.

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