Read UTF-8 text from a specified file, optionally selecting an inclusive range of one-based lines by start and end values.
Read UTF-8 text, optionally selecting an inclusive range of one-based lines.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| end_line | No | ||
| start_line | No |
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| text | Yes | ||
| resources | No | ||
| start_line | Yes |
Changes observed during successful MCP inspections.
v0.2.2Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real context beyond annotations: the content is UTF-8 text and line selection is inclusive and one-based. It does not disclose behavior for out-of-range lines, missing files, or encoding errors.
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?
A single tight sentence that front-loads the core action ('Read UTF-8 text') before the optional range qualifier. Every clause earns its place with no redundancy.
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 read tool, an output schema exists (so return values need no explanation) and annotations carry the safety profile. The description is nearly complete, missing only error/out-of-range behavior for the line-range feature.
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 carry parameter meaning. It does explain that start_line/end_line form an inclusive, one-based range, which is genuinely additive. However, it omits edge semantics (what happens if only one bound is supplied, or bounds exceed file length), so compensation is partial.
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+resource ('Read UTF-8 text' from a file) and the optional line-range capability. An agent can distinguish it from workspace_write_file/workspace_edit_file, but it never names or contrasts with the closest sibling for content retrieval (workspace_text_search, workspace_file_info).
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 word 'optionally' hints that the line range is not required, which is the only usage signal. There is no explicit when-to-use guidance versus text search or file info, nor any when-not-to-use or prerequisite statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.