Metis — Read Office Document

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

With no annotations, the description carries the full burden and does the most important work: it discloses that Excel returns STRUCTURE ONLY and never cell values, which is a non-obvious and safety-critical constraint an agent could not infer. It also describes exactly what each format returns. It omits error behavior for unsupported formats, size limits, and whether the path must already exist.

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?

Front-loaded with the one-line purpose, then organized per format and finally the argument, so an agent can stop reading as soon as it has what it needs. The safe-analysis explanation runs slightly long but is justified because it prevents an incorrect follow-up call.

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 single-path read tool, this covers everything an agent needs: accepted formats, return payload per format, the data-safety boundary, and where to go for actual analysis. An output schema exists, so the description did not have to explain return values, yet its format description is still accurate and adds routing value.

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 0%, so the description must compensate, and it does: it names the accepted extensions (.pptx, .xlsx) and defines the path resolution base ('absolute or relative to the Metis folder'). That is meaning the bare string schema does not convey. It stops short of clarifying behavior for other extensions.

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 ('Read a PowerPoint or Excel file into Metis') and then splits the behavior by format, so the agent knows exactly what comes back in each case. It is clearly distinguishable from file-reading siblings like read_file or ingest_office_document because the per-format payload is spelled out.

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?

Gives a concrete routing rule for the analysis case: if the data needs analysing, use the safe-analysis procedure rather than this tool. That is real when-not guidance. It does not, however, say when to prefer this over read_file, ingest_office_document, or extract_structured, so the sibling differentiation is incomplete.

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