Read Project File

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

Discloses substantial behavior beyond the readOnly/idempotent annotations: byte ranges are applied client-side AFTER fetching the whole file because the backend does not support partial transfers, full-file base64 can exceed MCP message limits, and byte-offset boundaries inside multi-byte UTF-8 characters decode to U+FFFD at the seam. It also documents the encoding auto-detect JSON envelope, metadata view, folder listing modes, and ZIP download behavior. No contradiction with annotations.

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?

Long but justified for 16 parameters and four distinct behavior modes; the purpose and endpoint are front-loaded and the numbered behavior modes make it scannable. Every sentence earns its place — there is no filler, and the critical memory/byte-range caveat is positioned before the closing use-case sentence.

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?

With no output schema, the description carries the return-value burden and covers the main shapes: verbatim UTF-8 text, base64 JSON envelope with byte and MIME metadata, metadata JSON (name, size, extension, lastModified), folder listings, and ZIP envelopes. Version/branch behavior and the MCP message-limit hazard are also covered, leaving no critical gap an agent would need to guess at.

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%, so the baseline is 3. The description adds coordinating semantics beyond individual parameter docs: how encoding behaves for file vs folder paths, that offset/length bounds the returned size after a full fetch, and the chunked-read strategy for large files. This clarifies parameter interplay that the schema's per-field descriptions do not convey.

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 any file in a project by its project-relative path' — and maps to a concrete endpoint (GET /projects/{projectId}/files/{path}). It distinguishes itself from the write/delete/search/copy/move project-file siblings by enumerating its full scope: file content, folder listings, metadata, and ZIP downloads.

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 explicit when-to-use guidance ('Use this to read AGENTS.md, README.md, schemas, manifests, or to inspect/export xlsx rule files') that makes intended use concrete. It does not explicitly name exclusions or say 'use X instead for Y', so differentiation from alternatives rests on the read-only scope, the endpoint mapping, and sibling names rather than an explicit routing statement.

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