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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, non-idempotent) by disclosing that the call runs in the background, returns a call_id that must be polled via account_get_call, holds $0.005 per page read then charges actual pages, and is free if no pages are read. The cost model and async lifecycle are exactly the context annotations cannot express.

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?

Dense but front-loaded: purpose and input constraints come first, then persistence, cost, and async behavior. Every sentence carries information, though the pricing idea is stated twice ('holds $0.005 for each until…' and 'Costs $0.005 per page read'), which could be merged.

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?

With no output schema, the description still tells the agent what comes back (a call_id) and how to retrieve the result, plus where the extracted text lives afterwards. For a three-parameter, paid, asynchronous tool, nothing needed to invoke it 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 67%, and the description compensates for the gap: max_pages is explained as a billing cap (hold then settle) rather than just a maximum, and languages notes the default comes from the account and is capped at 3. file_id's origin ('files_upload returned') is left to the schema, which already covers it.

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 ('Read the words in a scan with OCR') plus the accepted inputs (PNG, JPEG, TIFF, WebP, scanned PDF pages) and scope (up to 100 pages). It implicitly carves out scanned/no-text pages but never names the sibling tool that handles PDFs with a text layer (documents_read_pdf), leaving the closest alternative undifferentiated.

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?

Clearly says when to use it: images or PDF pages that have no text of their own, and notes that pages already carrying text keep it. It also routes the agent to files_read_text for the follow-up and files_ocr_settings for language defaults, but gives no explicit 'use X instead when…' exclusion for text-based PDFs.

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