read_local_file

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered structurally. The description adds real behavioral context beyond that: paged/chunked output for long files and the fact that audio/video are not directly readable. It stops short of describing error behavior or the shape of the paged return.

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 sentences with no filler, and the format list is front-loaded so the agent learns scope immediately. The pagination and audio/video notes follow in a logical order. Slightly dense format enumeration is the only cost.

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 read-only tool with no output schema, the description covers formats, chunking behavior, and an important input boundary. The gaps (max_chars semantics, what happens on unreadable/oversized files) are minor given the annotations already convey the safe-read profile.

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. It partially does for offset by explaining the pagination round-trip, but it references a 'next_offset' field that is not an actual parameter, and max_chars (page size) and path are never explained. Meaning is added for one of three parameters only.

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 the specific resource ('Plain text of a local document') and enumerates supported formats (PDF, DOCX, XLSX, PPTX, CSV, JSON, Markdown, TXT, VTT/SRT), which pins down exactly what 'read' returns. It does not explicitly contrast with the sibling list_local_files, but the read-vs-list distinction is inferable from the names.

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?

It gives two usable constraints: pagination ('Long files come in pages: pass next_offset back as offset') and a boundary ('Audio and video need a transcript first'). However, it never states when to prefer this tool over list_local_files or what to do for unsupported inputs, so guidance is implied rather than explicit.

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