document_processor

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

Annotations already carry destructiveHint=true and idempotentHint=false, so the mutation profile is established. The description adds genuinely useful context beyond annotations: it reads from the local filesystem/sandbox and writes results back locally. It does not, however, disclose nuances like potential overwriting of the outputPath, long-running OCR/processing times, or that applied redactions permanently alter content — though the schema's createRedactions/applyRedactions two-step does hint at the workflow.

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?

The description is front-loaded with the core purpose, then organized into tight bullet groups for features and output formats, closing with a valuable sibling-routing note. Every line earns its place and the list format aids scanning. A small redundancy exists — the output format list partially mirrors the schema's output.anyOf variants — but it is useful as a quick capability overview without needing to open the schema.

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?

Given the tool's enormous complexity (2 required params, nested instructions object, 8 output variants, 7 action types), the description gives an agent a solid entry point: what it does, its main capabilities, output formats, I/O behavior, and the key exclusion. The schema and its rich descriptions carry the operational detail, which is appropriate. The only notable omission is guidance on how this tool's redaction capabilities relate to the ai_redactor 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 description coverage is 100%, so the baseline is 3. The schema already exhaustively documents instructions, parts, output variants, and actions with detailed descriptions. The description adds only marginal parameter-level value — it restates the high-level feature set and the local/sandbox path resolution, but does not meaningfully augment the schema's parameter documentation.

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 phrase — 'Process, convert, and transform documents using the Nutrient API' — and supports it with a concrete feature list (XFDF import, flatten, OCR, rotation, watermarking, redaction) and output format list (PDF, PDF/A, images, Office, HTML, Markdown). It also explicitly differentiates itself from the parse_document sibling by name and by what that alternative does better (typed JSON/Markdown with bounding boxes and confidence scores).

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?

The description gives one explicit routing rule: for structured data extraction, 'use the dedicated parse_document tool instead.' It also clarifies the file I/O context (local file system vs. sandbox). However, it doesn't address other potentially overlapping siblings such as ai_redactor (which also performs redaction) or extract_fields, so the guidance is clear but not comprehensive across the full sibling set.

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