convert

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety/scope profile is covered. The description adds useful texture beyond that – OCR modes, password-protected input, text-layer-only fast paths – which signals this is a heavyweight, potentially slow conversion. It says nothing about size limits, where output is delivered, or error behavior for unsupported formats.

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?

A single sentence, front-loaded with verb and resource, with the format and option lists as trailing parentheticals. It is dense but every clause is relevant; the main inefficiency is that the enumerated formats largely duplicate the `to` schema, making the sentence longer than it needs to be.

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?

For a tool with an open-ended nested `options` object (additionalProperties: true) and no output schema, the description does point to docs/OPTIONS.md and gives representative option keys, which is helpful. However, it never characterizes the return value despite the wildly different shapes (plain text, DoclingDocument JSON, chunk records, VTT), nor does it cover how the open-ended options object relates to the server's supported set.

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 format list in the description essentially restates the `to` parameter's schema description, and the option examples (pages, ocr_lang, text_layer_only, do_picture_ocr, password) duplicate what the `options` schema already documents, so it adds little meaning beyond structured fields.

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 names a concrete verb (Convert) plus the resource (a document given by URI or path) and enumerates the eight supported output formats, so an agent immediately knows what it does. It references convert_to_markdown for input semantics but never contrasts itself with it or with list_input_formats, so sibling differentiation is only implied.

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 rather than stated: the '(URI or path, as convert_to_markdown)' aside hints this shares input handling with the sibling, and listing conversion options suggests it is the richer variant. There is no explicit when-to-use / when-not-to-use guidance and the sibling convert_to_markdown is never ruled in or out.

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