Extract data from an uploaded document

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

Annotations only supply openWorldHint=true, so the description carries most of the burden and does disclose real behavior: the call blocks and waits for the result, and it documents the full credit cost model including per-page upload and extraction pricing. It omits failure/retry behavior, permission requirements, and what happens when the document is not yet fully processed – a real gap for a paid, blocking operation.

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?

Purpose and the sibling alternative are front-loaded, and the pricing block is dense but information-bearing rather than filler. The semicolon-chained credit sentence is somewhat hard to parse, but each clause carries distinct cost information an agent needs before calling a paid operation.

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 should say what comes back and how to retrieve results asynchronously; instead it only implies JSON via save_to. The wait/get_standardization follow-up path and the shape of the returned extraction are unspecified, which matters for a job-style tool with a documented polling sibling.

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 71%, and the description adds genuine meaning beyond it: omitting schema_id triggers drafting at 1 credit/page capped at 5 pages (free if built from json_schema), effort_level costs 2 vs 4 credits/page, and citations force standard effort at 3 credits – an interaction between two params that the schema never states. The guidelines and document_id parameters gain no added meaning, keeping this below a 5.

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 ('Run an extraction (standardization) on one uploaded, fully processed document') and constrains the input to already-uploaded, pre-processed documents. It explicitly distinguishes itself from the sibling 'extract' by scoping that tool to starting from a file.

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?

Names the alternative ('use extract instead when starting from a file') with the exact condition that selects it, which is strong guidance. However, it gives no guidance on the wait=true vs wait=false path or on when to follow up with get_standardization, leaving that choice to inference.

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