code.read_file

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

With no annotations, the description carries full behavioral burden. It discloses that only non-secret files within workspaceRoot are readable, implying read-only behavior and a scope restriction. However, it does not disclose return format, error handling (e.g., missing files, exceeding maxBytes), or permission requirements, leaving gaps for an agent.

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?

The description is a single, compact sentence with no filler. It front-loads the core action and scope, and every word adds value. This is appropriately concise for a simple read tool.

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 no output schema, no annotations, and 0% schema coverage, the description must provide complete context for the agent. It omits key details such as how maxBytes behaves, what happens for missing or oversized files, and the return value format. While the tool is simple, the description leaves several operational unknowns.

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 gives minimal context for 'path' (inside workspaceRoot) but says nothing about 'maxBytes' or its meaning. The description adds very little value beyond the schema's type and required fields, failing to explain key parameter behavior.

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 uses the specific verb 'Read' and the resource 'non-secret file inside workspaceRoot', clearly distinguishing this from sibling tools like code.search_code (search) and code.apply_patch (modify). The qualifier 'non-secret' adds an important scope boundary, making the purpose unambiguous.

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 need to read a file, but it does not explicitly state when to use this tool versus alternatives (e.g., search_code for searching, apply_patch for modifications). The 'non-secret' qualifier provides a minor exclusion (don't use for secret files), but no clear context or naming of alternatives is given.

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