xlsx_to_markdown

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

With no annotations, the description carries full behavioral burden. It discloses the cost ($0.01) and the per-sheet output structure, which is useful. However, it doesn't mention whether the operation is read-only, how large files are handled, potential formatting loss, or that the output parameter can return JSON instead of Markdown—a significant behavioral gap.

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 plus a price tag, front-loaded with the core purpose and output format. No wasted words; every element earns its place.

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 5 parameters, no annotations, and no output schema, the description is incomplete. It fails to explain the output options (md vs json), max_rows, output_path, and idempotency_key, and it directly contradicts the schema's default output format. This is likely to cause an agent to call the tool expecting Markdown tables and receive JSON.

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 0%, so the description must compensate, but it only clarifies the `file` parameter (local .xlsx path). It misleadingly states output is Markdown tables while the schema default for `output` is 'json'. The other parameters (`max_rows`, `output_path`, `idempotency_key`) are entirely unexplained, leaving an agent unable to invoke the tool correctly beyond the simplest call.

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: 'Extract a spreadsheet (.xlsx, local path) as Markdown tables, one section per sheet.' It clearly distinguishes from sibling converters like docx_to_markdown and pptx_to_markdown by file type and output structure. The cost disclosure is a useful extra, not a distraction.

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 implies usage: when you have a local .xlsx and want Markdown tables per sheet. But it offers no explicit when-to-use vs alternatives, no exclusions, and no guidance about the output parameter or other options. The 'local path' qualifier hints at a constraint but doesn't state it as a hard rule.

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