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

Annotations already declare readOnly, openWorld, non-idempotent and non-destructive, and the description adds substantial context beyond them: per-call pricing, a free tier, size limits (10 MB, 3 MB for images), which inputs fail and that failures are uncharged, and that repeat calls are billed so results are not cached. Those cost and failure semantics are exactly the operational facts an agent needs before deciding to call twice.

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?

Key facts are front-loaded (formats first, then input, then limits, then cost), but the prose is a dense run-on and the failure-freeness is stated twice ('fail uncharged' and 'failed calls free'), with the price/credits sentence adding bulk at the tail. It is informative but not tight.

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 3-parameter conversion tool with no output schema, the description covers accepted inputs, traversal semantics, size limits, failure modes and cost, which is nearly everything needed to call it correctly. The remaining gap is what happens when maxChars truncates output, which is left to inference.

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 parameters are already documented; the description still adds meaning by contrasting the two ingest paths (public URL versus POST body) and clarifying that 'markdown' preserves headings, lists and tables while 'text' does not. It says nothing extra about maxChars truncation behavior, which limits the gain.

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 opens with a specific verb and resource ('Convert a document to text or Markdown') and then enumerates exactly which formats are handled and how each is traversed (xlsx sheet by sheet, pptx slide by slide, PDF text, OCR for scans). This scope statement lets an agent distinguish it from narrower siblings such as pdf_text or document_extract 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?

It gives a clear use context ('read attachments, scans and spreadsheets into an agent, RAG or a workflow') and a concrete invocation example with a sample URL. It does not explicitly name when to prefer a sibling tool (e.g. a PDF-only converter) or state exclusions beyond the unsupported legacy formats, so guidance stops short of full alternative routing.

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