Convert documents

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

Annotations declare non-read-only, non-destructive, non-idempotent, and the description usefully explains why: it writes new outputs beside the input and replaces nothing unless overwrite is true, which materially clarifies the safety profile. It also discloses that multiple inputs are supported and that markup mode changes output content. It stops short of stating permissions or failure behavior.

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?

Three tight clauses, front-loaded with the conversion scope, and every sentence carries information about formats or output placement. The 'doc (read)' and 'png (first page)' parentheticals introduce minor ambiguity rather than clarity.

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?

There is no output schema, so the description must fully specify behavior; it covers output location and overwrite but omits how the several optional input parameters interact and what the tool returns per file. Adequate for a conversion tool with no required parameters, but not complete.

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?

With 63% schema coverage, the description adds real value for markup, overwrite, and output placement. However, the mutual exclusivity/priority among input_path, input_paths, and input_dir is never explained — a significant gap for an agent choosing among them — and 'png (first page)' conflicts subtly with the schema's 'one image per page' wording.

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 (convert) and resource (documents), and enumerates the supported target formats, so the core operation is unambiguous. It does not differentiate from siblings that overlap in output (render_pages for png, extract_text for txt, create_document for docx), leaving the agent to infer boundaries.

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?

Usage is implied by the format list and by 'Outputs go next to each input or into output_dir', but there is no explicit when-to-use/when-not statement and no sibling alternative is named despite clear overlap with render_pages and extract_text.

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