Give AI agents a document tool with a real control plane

Define the tool boundary

An agent should express intent—parse this permitted file and return structure—not infrastructure—run this model against an arbitrary URL. Keep API keys in the tool server, enforce source and webhook allowlists, and expose a narrow schema that includes source name, size, processing intent, and idempotency key.

Return explicit states. A queued job is not a parsed document, and a failed job should not be transformed into an empty success response. DocParse provides terminal error codes, lifecycle events, and result availability rules an agent can reason about.

Use structured output for tool decisions

Markdown is effective when the next action is summarization or question answering. DocIR is useful when the agent must locate a table, cite a page, inspect a heading hierarchy, or route only certain block types to another tool.

Keep the raw parser result outside the model context when it is large. The tool can select relevant blocks, provide a compact manifest, and let the agent request a page or section by stable identifier.

• Give the model a compact job and source summary first.
• Retrieve blocks on demand instead of injecting the entire document.
• Require confirmation before destructive purge actions.
• Log tool inputs, job IDs, outcomes, and derived actions without logging secrets.

Bound autonomous cost and retries

Agents retry. Use an idempotency key tied to the source and desired parse options so a repeated plan does not create duplicate jobs. Respect 429 retry guidance, stop on non-retryable media errors, and cap the number of polling attempts.

High-cost processing should be a capability granted to the workspace, not a prompt-controlled flag. DocParse reserves model/provider attempts in durable accounting and denies trial requests that require model-backed image or layout work.