agent-tool

Overview Schema Source Related Servers Discussions Admin

read

Retrieve file contents with encoding detection, line numbers, and pagination. Returns text with truncation info or raster images as image content; supports offsets and relative paths.

Instructions

Read text with line numbers or return raster images as ImageContent. Detects common encodings; SVG stays text. Text is bounded and reports truncation/next_offset. Use offset/limit to page; relative paths use the workspace or MCP root.

Input Schema

TableJSON Schema

Name	Required	Description
`all`	No	Disable line cap; character cap remains
`path`	No	Alias for file_path
`limit`	No	Line limit; default 400. Use 0 or all=true for no line cap
`offset`	No	Start line: 1-based integer, negative from end, 'start-end', or [start,end]; default 1
`end_line`	No	Inclusive end with start_line
`file_path`	No	Absolute or workspace/MCP-root-relative file path
`start_line`	No	Alias for offset
`include_hash`	No	Include SHA-256; default true
`max_line_chars`	No	Per-line character cap; default 4000, max 32768
`max_output_chars`	No	Output character cap; default 32768, max 131072

Schema Changelog

Changes observed during successful MCP inspections.

Changed11 schema fields changedv0.9.7Sep 16, 2026

changedInput schema / properties / all / description

Previous value: -"Remove the default line limit. The max_output_chars safety budget still applies. Default: false"New value: +"Disable line cap; character cap remains"

changedInput schema / properties / end_line / description

Previous value: -"Inclusive end line used with start_line"New value: +"Inclusive end with start_line"

changedInput schema / properties / file_path / description

Previous value: -"Absolute or workspace-relative path to the file to read"New value: +"Absolute or workspace/MCP-root-relative file path"

changedInput schema / properties / include_hash / description

Previous value: -"Include SHA-256 for optimistic edit concurrency. Default: true"New value: +"Include SHA-256; default true"

changedInput schema / properties / limit / description

Previous value: -"Maximum lines to return. Default: 400. Set 0 or all=true to remove the line limit; the character budget still applies"New value: +"Line limit; default 400. Use 0 or all=true for no line cap"

changedInput schema / properties / max_line_chars / description

Previous value: -"Maximum characters returned from one line. Default: 4000, Max: 32768"New value: +"Per-line character cap; default 4000, max 32768"

changedInput schema / properties / max_output_chars / description

Previous value: -"Maximum returned text characters. Default: 32768, Max: 131072"New value: +"Output character cap; default 32768, max 131072"

changedInput schema / properties / offset / description

Previous value: -"Line offset. Integer (1-based, negative=from end), string range 'start-end', or [start,end] array. Default: 1"New value: +"Start line: 1-based integer, negative from end, 'start-end', or [start,end]; default 1"

addedInput schema / properties / offset / type
```
Added value: +"integer"
```

changedInput schema / properties / path / description

Previous value: -"Compatibility alias for file_path; prefer file_path"New value: +"Alias for file_path"

changedInput schema / properties / start_line / description

Previous value: -"Compatibility alias for offset; prefer offset"New value: +"Alias for offset"

Changed13 schema fields changedv0.9.5Aug 25, 2026

addedInput schema / properties / all

Added value: +{
+  "description": "Remove the default line limit. The max_output_chars safety budget still applies. Default: false",
+  "type": "boolean"
+}

changedInput schema / properties / end_line / description

Previous value: -"End line number (1-based, inclusive). Sets limit = end_line - start_line + 1 when used with start_line"New value: +"Inclusive end line used with start_line"

addedInput schema / properties / end_line / type
```
Added value: +[
+  "null",
+  "integer"
+]
```

changedInput schema / properties / file_path / description

Previous value: -"Absolute or relative path to the file to read"New value: +"Absolute or workspace-relative path to the file to read"

addedInput schema / properties / include_hash

Added value: +{
+  "description": "Include SHA-256 for optimistic edit concurrency. Default: true",
+  "type": [
+    "null",
+    "boolean"
+  ]
+}

changedInput schema / properties / limit / description

Previous value: -"Maximum number of lines to read. Default: 0 (all)"New value: +"Maximum lines to return. Default: 400. Set 0 or all=true to remove the line limit; the character budget still applies"

addedInput schema / properties / limit / type

Added value: +[
+  "null",
+  "integer"
+]

addedInput schema / properties / max_line_chars

Added value: +{
+  "description": "Maximum characters returned from one line. Default: 4000, Max: 32768",
+  "type": "integer"
+}

addedInput schema / properties / max_output_chars

Added value: +{
+  "description": "Maximum returned text characters. Default: 32768, Max: 131072",
+  "type": "integer"
+}

changedInput schema / properties / offset / description

Previous value: -"Line offset. Integer (1-based, negative=from end), string range 'start-end', or [start,end] array. Default: 0 (all)"New value: +"Line offset. Integer (1-based, negative=from end), string range 'start-end', or [start,end] array. Default: 1"

changedInput schema / properties / path / description

Previous value: -"Alias for file_path"New value: +"Compatibility alias for file_path; prefer file_path"

changedInput schema / properties / start_line / description

Previous value: -"Alias for offset (1-based line number to start reading from)"New value: +"Compatibility alias for offset; prefer offset"

addedInput schema / properties / start_line / type
```
Added value: +[
+  "null",
+  "integer"
+]
```

Addedv0.8.7May 6, 2026
RemovedApr 30, 2026

Changed3 schema fields changedv0.7.12Mar 26, 2026

changedInput schema / properties / offset / description

Previous value: -"Line number to start reading from (1-based). Negative = from end (e.g. -5 = last 5 lines). Default: 1"New value: +"Line offset. Integer (1-based, negative=from end), string range 'start-end', or [start,end] array. Default: 0 (all)"

removedInput schema / properties / offset / type
```
Removed value: -"integer"
```

changedOutput schema / (root)

Previous value: -{
-  "additionalProperties": false,
-  "properties": {
-    "content": {
-      "type": "string"
-    },
-    "encoding": {
-      "type": "string"
-    },
-    "hash": {
-      "type": "string"
-    },
-    "total_lines": {
-      "type": "integer"
-    }
-  },
-  "required": [
-    "content",
-    "encoding",
-    "total_lines"
-  ],
-  "type": "object"
-}New value: +null

First observedv0.4.2Mar 14, 2026

TDQS

A3.9/5.0

Behavior4/5

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

With no annotations at all, the description carries the full burden and addresses key behaviors: encoding detection, SVG staying text, bounded output with truncation/next_offset reporting, and image results as ImageContent. It does not discuss permissions or failure modes, but for a read operation it discloses the traits most likely to surprise 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences front-load the core behavior and pack each line with non-redundant detail (images, encoding, truncation, paging, paths). No sentence is wasted and the structure lets an agent scan quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter, 0-required, no-output-schema tool, the description covers the most important invocation concerns: return type, encoding edge case, truncation reporting, paging, and path base. It does not spell out all optional parameters, but those are fully documented in the schema, so an agent can call the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds value beyond the schema by explaining paging semantics ('Use offset/limit to page') and relative path resolution ('workspace or MCP root'). This helps disambiguate offset/limit and file_path without repeating every schema field.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific action ('Read text') and a clear resource, and covers the image-return case ('raster images as ImageContent'), going beyond a bare tautology. It does not explicitly name a sibling such as multiread to differentiate, but the core behavior is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives actionable context for paging ('Use offset/limit to page') and path interpretation ('relative paths use the workspace or MCP root'), which helps an agent decide how to call it. However, it provides no explicit guidance on when to prefer a sibling like multiread or grep, so the when-vs-alternatives guidance is implied rather than stated.

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

Deploy Server

read

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools