Parse a document into a spec

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

With no annotations, description carries full burden. It discloses that pptx/docx parsing will error and that xlsx parsing includes data and headers. Does not mention destructive actions, rate limits, or authentication, but the read-only nature is implied by 'read' verb.

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?

Two sentences with zero waste. Front-loaded with action and immediately addresses constraints. Every sentence provides essential information.

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 simple two-param tool with no output schema, the description covers the core purpose, supported format, and error cases. Lacks explanation of what a 'spec' is, but this is likely understood from domain context.

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 coverage is 100%, but description adds context beyond schema by noting format support and that pptx/docx will error. This helps the agent understand the enum values behaviorally.

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?

Description clearly states verb 'Read' and resource 'exisiting file' into a spec, and specifies supported format (xlsx) and that pptx/docx will error. Differentiates from sibling tools like convert_document or preview_document by focusing on parsing back to spec.

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?

Explicitly states current support is only for xlsx and that pptx/docx will error, providing clear when-to-use guidance. Does not explicitly name alternatives for pptx/docx, but the context of sibling tools implies they may handle those formats.

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