Skip to main content
Glama

Read File

read
Read-only

Retrieve file contents from the filesystem: read text files whole or by line slices, images and audio as media, or any binary file as base64 via the binary flag.

Instructions

Read text files, like cat: whole, or one slice via head, tail, or startLine/endLine. Images and audio return as media; pass binary: true to get any other binary file whole as a base64 embedded resource.

Input Schema

NameRequiredDescriptionDefault
headNoReturn first N lines
pathNoSingle file path; mutually exclusive with paths
tailNoReturn last N lines
pathsNoArray of file paths for batch mode (max 1000); mutually exclusive with path
binaryNoReturn a binary file that is not an image or audio whole, as a base64 embedded resource. Full reads only.
endLineNoEnd line (1-indexed); requires startLine
startLineNoStart line (1-indexed)
includeHashNoInclude SHA-256 hash of the returned content in the response

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv2.9.1
    • removedInput schema / dependentRequired
      Removed value: -{
      -  "endLine": [
      -    "startLine"
      -  ]
      -}
    • removedInput schema / oneOf
      Removed value: -[
      -  {
      -    "required": [
      -      "path"
      -    ]
      -  },
      -  {
      -    "required": [
      -      "paths"
      -    ]
      -  }
      -]
    • addedInput schema / properties / binary
      Added value: +{
      +  "default": false,
      +  "description": "Return a binary file that is not an image or audio whole, as a base64 embedded resource. Full reads only.",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / endLine / description
      Previous value: -"End line (1-indexed)"New value: +"End line (1-indexed); requires startLine"
  2. Changed2 schema fields changedv2.8.1
    • changedInput schema / properties / endLine / maximum
      Previous value: -100000New value: +2147483647
    • changedInput schema / properties / startLine / maximum
      Previous value: -100000New value: +2147483647
  3. Changed1 schema field changedv2.4.1
    • addedInput schema / $schema
      Added value: +"https://json-schema.org/draft/2020-12/schema"
  4. Changed1 schema field changedv2.1.5
    • changedOutput schema / (root)
      Previous value: -{
      -  "additionalProperties": false,
      -  "properties": {
      -    "results": {
      -      "description": "Per-path results ordered to match the input paths",
      -      "items": {
      -        "additionalProperties": false,
      -        "properties": {
      -          "error": {
      -            "additionalProperties": false,
      -            "description": "Error details; present on failure",
      -            "properties": {
      -              "code": {
      -                "type": "string"
      -              },
      -              "message": {
      -                "type": "string"
      -              },
      -              "path": {
      -                "type": "string"
      -              },
      -              "suggestion": {
      -                "type": "string"
      -              }
      -            },
      -            "required": [
      -              "code",
      -              "message"
      -            ],
      -            "type": "object"
      -          },
      -          "path": {
      -            "description": "Requested file path",
      -            "type": "string"
      -          },
      -          "value": {
      -            "additionalProperties": false,
      -            "description": "Read result; present on success",
      -            "properties": {
      -              "contentHash": {
      -                "description": "SHA-256 hex digest of the returned content (present when includeHash=true)",
      -                "pattern": "^[0-9a-f]{64}$",
      -                "type": "string"
      -              },
      -              "continuation": {
      -                "additionalProperties": false,
      -                "description": "Next-read arguments; present when content was truncated due to size limits",
      -                "properties": {
      -                  "args": {
      -                    "additionalProperties": false,
      -                    "description": "Ready-to-use arguments for the next call; pass verbatim",
      -                    "properties": {
      -                      "endLine": {
      -                        "exclusiveMinimum": 0,
      -                        "type": "integer"
      -                      },
      -                      "path": {
      -                        "type": "string"
      -                      },
      -                      "startLine": {
      -                        "exclusiveMinimum": 0,
      -                        "type": "integer"
      -                      }
      -                    },
      -                    "required": [
      -                      "path",
      -                      "startLine",
      -                      "endLine"
      -                    ],
      -                    "type": "object"
      -                  },
      -                  "hint": {
      -                    "description": "One-sentence description of the data still remaining to be read",
      -                    "type": "string"
      -                  },
      -                  "tool": {
      -                    "description": "Tool name to call for the next chunk",
      -                    "type": "string"
      -                  }
      -                },
      -                "required": [
      -                  "tool",
      -                  "args",
      -                  "hint"
      -                ],
      -                "type": "object"
      -              },
      -              "endLine": {
      -                "description": "End line",
      -                "exclusiveMinimum": 0,
      -                "type": "integer"
      -              },
      -              "hasMoreLines": {
      -                "description": "True when additional lines remain beyond what was returned",
      -                "type": "boolean"
      -              },
      -              "head": {
      -                "description": "Head lines requested",
      -                "exclusiveMinimum": 0,
      -                "type": "integer"
      -              },
      -              "kind": {
      -                "description": "Broad file kind: text, binary, image, audio, or pdf",
      -                "enum": [
      -                  "text",
      -                  "binary",
      -                  "image",
      -                  "audio",
      -                  "pdf"
      -                ],
      -                "type": "string"
      -              },
      -              "linesRead": {
      -                "description": "Number of lines returned in this response",
      -                "minimum": 0,
      -                "type": "integer"
      -              },
      -              "mimeType": {
      -                "description": "Detected MIME type (e.g. text/typescript)",
      -                "type": "string"
      -              },
      -              "resourceUri": {
      -                "description": "Resource URI for externalized content (present when file is stored in resource store)",
      -                "type": "string"
      -              },
      -              "startLine": {
      -                "description": "Start line",
      -                "exclusiveMinimum": 0,
      -                "type": "integer"
      -              },
      -              "tail": {
      -                "description": "Tail lines requested",
      -                "exclusiveMinimum": 0,
      -                "type": "integer"
      -              },
      -              "totalLines": {
      -                "description": "Total line count in the full file",
      -                "minimum": 0,
      -                "type": "integer"
      -              }
      -            },
      -            "type": "object"
      -          }
      -        },
      -        "required": [
      -          "path"
      -        ],
      -        "type": "object"
      -      },
      -      "type": "array"
      -    },
      -    "summary": {
      -      "additionalProperties": false,
      -      "properties": {
      -        "failed": {
      -          "minimum": 0,
      -          "type": "integer"
      -        },
      -        "succeeded": {
      -          "minimum": 0,
      -          "type": "integer"
      -        },
      -        "total": {
      -          "minimum": 0,
      -          "type": "integer"
      -        }
      -      },
      -      "required": [
      -        "total",
      -        "succeeded",
      -        "failed"
      -      ],
      -      "type": "object"
      -    }
      -  },
      -  "required": [
      -    "results",
      -    "summary"
      -  ],
      -  "type": "object"
      -}New value: +null
  5. Changed31 schema fields changedv2.0.0
    • removedInput schema / $schema
      Removed value: -"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / dependentRequired
      Added value: +{
      +  "endLine": [
      +    "startLine"
      +  ]
      +}
    • removedInput schema / description
      Removed value: -"Use one read mode only: 'head', 'tail', or 'startLine'/'endLine'."
    • addedInput schema / oneOf
      Added value: +[
      +  {
      +    "required": [
      +      "path"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "paths"
      +    ]
      +  }
      +]
    • changedInput schema / properties / endLine / description
      Previous value: -"End line (1-based, inclusive). Defaults to last line when startLine is set."New value: +"End line (1-indexed)"
    • changedInput schema / properties / endLine / maximum
      Previous value: -9007199254740991New value: +100000
    • changedInput schema / properties / head / description
      Previous value: -"Read first N lines (preview)"New value: +"Return first N lines"
    • changedInput schema / properties / includeHash / description
      Previous value: -"Include SHA-256 hash of full file content"New value: +"Include SHA-256 hash of the returned content in the response"
    • changedInput schema / properties / path / description
      Previous value: -"Absolute path to file or directory."New value: +"Single file path; mutually exclusive with paths"
    • addedInput schema / properties / paths
      Added value: +{
      +  "description": "Array of file paths for batch mode (max 1000); mutually exclusive with path",
      +  "items": {
      +    "description": "File or directory path inside an allowed workspace root.",
      +    "maxLength": 4096,
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "maxItems": 1000,
      +  "minItems": 1,
      +  "type": "array"
      +}
    • changedInput schema / properties / startLine / description
      Previous value: -"Start line (1-based, inclusive). Defaults to 1 when endLine is set."New value: +"Start line (1-indexed)"
    • changedInput schema / properties / startLine / maximum
      Previous value: -9007199254740991New value: +100000
    • changedInput schema / properties / tail / description
      Previous value: -"Read last N lines"New value: +"Return last N lines"
    • removedInput schema / required
      Removed value: -[
      -  "path"
      -]
    • removedOutput schema / $schema
      Removed value: -"https://json-schema.org/draft/2020-12/schema"
    • removedOutput schema / properties / content
      Removed value: -{
      -  "description": "Content",
      -  "type": "string"
      -}
    • removedOutput schema / properties / contentHash
      Removed value: -{
      -  "description": "SHA-256 of full file content",
      -  "pattern": "^[a-f0-9]{64}$",
      -  "type": "string"
      -}
    • removedOutput schema / properties / endLine
      Removed value: -{
      -  "description": "End line",
      -  "maximum": 9007199254740991,
      -  "minimum": 1,
      -  "type": "integer"
      -}
    • removedOutput schema / properties / hasMoreLines
      Removed value: -{
      -  "description": "More lines?",
      -  "type": "boolean"
      -}
    • removedOutput schema / properties / head
      Removed value: -{
      -  "description": "Head lines",
      -  "maximum": 9007199254740991,
      -  "minimum": 1,
      -  "type": "integer"
      -}
    • removedOutput schema / properties / linesRead
      Removed value: -{
      -  "description": "Lines read",
      -  "maximum": 9007199254740991,
      -  "minimum": 0,
      -  "type": "integer"
      -}
    • removedOutput schema / properties / ok
      Removed value: -{
      -  "const": true,
      -  "type": "boolean"
      -}
    • removedOutput schema / properties / path
      Removed value: -{
      -  "type": "string"
      -}
    • removedOutput schema / properties / resourceUri
      Removed value: -{
      -  "description": "Full content URI",
      -  "type": "string"
      -}
    • addedOutput schema / properties / results
      Added value: +{
      +  "description": "Per-path results ordered to match the input paths",
      +  "items": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "error": {
      +        "additionalProperties": false,
      +        "description": "Error details; present on failure",
      +        "properties": {
      +          "code": {
      +            "type": "string"
      +          },
      +          "message": {
      +            "type": "string"
      +          },
      +          "path": {
      +            "type": "string"
      +          },
      +          "suggestion": {
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "code",
      +          "message"
      +        ],
      +        "type": "object"
      +      },
      +      "path": {
      +        "description": "Requested file path",
      +        "type": "string"
      +      },
      +      "value": {
      +        "additionalProperties": false,
      +        "description": "Read result; present on success",
      +        "properties": {
      +          "contentHash": {
      +            "description": "SHA-256 hex digest of the returned content (present when includeHash=true)",
      +            "pattern": "^[0-9a-f]{64}$",
      +            "type": "string"
      +          },
      +          "continuation": {
      +            "additionalProperties": false,
      +            "description": "Next-read arguments; present when content was truncated due to size limits",
      +            "properties": {
      +              "args": {
      +                "additionalProperties": false,
      +                "description": "Ready-to-use arguments for the next call; pass verbatim",
      +                "properties": {
      +                  "endLine": {
      +                    "exclusiveMinimum": 0,
      +                    "type": "integer"
      +                  },
      +                  "path": {
      +                    "type": "string"
      +                  },
      +                  "startLine": {
      +                    "exclusiveMinimum": 0,
      +                    "type": "integer"
      +                  }
      +                },
      +                "required": [
      +                  "path",
      +                  "startLine",
      +                  "endLine"
      +                ],
      +                "type": "object"
      +              },
      +              "hint": {
      +                "description": "One-sentence description of the data still remaining to be read",
      +                "type": "string"
      +              },
      +              "tool": {
      +                "description": "Tool name to call for the next chunk",
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "tool",
      +              "args",
      +              "hint"
      +            ],
      +            "type": "object"
      +          },
      +          "endLine": {
      +            "description": "End line",
      +            "exclusiveMinimum": 0,
      +            "type": "integer"
      +          },
      +          "hasMoreLines": {
      +            "description": "True when additional lines remain beyond what was returned",
      +            "type": "boolean"
      +          },
      +          "head": {
      +            "description": "Head lines requested",
      +            "exclusiveMinimum": 0,
      +            "type": "integer"
      +          },
      +          "kind": {
      +            "description": "Broad file kind: text, binary, image, audio, or pdf",
      +            "enum": [
      +              "text",
      +              "binary",
      +              "image",
      +              "audio",
      +              "pdf"
      +            ],
      +            "type": "string"
      +          },
      +          "linesRead": {
      +            "description": "Number of lines returned in this response",
      +            "minimum": 0,
      +            "type": "integer"
      +          },
      +          "mimeType": {
      +            "description": "Detected MIME type (e.g. text/typescript)",
      +            "type": "string"
      +          },
      +          "resourceUri": {
      +            "description": "Resource URI for externalized content (present when file is stored in resource store)",
      +            "type": "string"
      +          },
      +          "startLine": {
      +            "description": "Start line",
      +            "exclusiveMinimum": 0,
      +            "type": "integer"
      +          },
      +          "tail": {
      +            "description": "Tail lines requested",
      +            "exclusiveMinimum": 0,
      +            "type": "integer"
      +          },
      +          "totalLines": {
      +            "description": "Total line count in the full file",
      +            "minimum": 0,
      +            "type": "integer"
      +          }
      +        },
      +        "type": "object"
      +      }
      +    },
      +    "required": [
      +      "path"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • removedOutput schema / properties / startLine
      Removed value: -{
      -  "description": "Start line",
      -  "maximum": 9007199254740991,
      -  "minimum": 1,
      -  "type": "integer"
      -}
    • addedOutput schema / properties / summary
      Added value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "failed": {
      +      "minimum": 0,
      +      "type": "integer"
      +    },
      +    "succeeded": {
      +      "minimum": 0,
      +      "type": "integer"
      +    },
      +    "total": {
      +      "minimum": 0,
      +      "type": "integer"
      +    }
      +  },
      +  "required": [
      +    "total",
      +    "succeeded",
      +    "failed"
      +  ],
      +  "type": "object"
      +}
    • removedOutput schema / properties / tail
      Removed value: -{
      -  "description": "Tail lines",
      -  "maximum": 9007199254740991,
      -  "minimum": 1,
      -  "type": "integer"
      -}
    • removedOutput schema / properties / totalLines
      Removed value: -{
      -  "description": "Total lines",
      -  "maximum": 9007199254740991,
      -  "minimum": 0,
      -  "type": "integer"
      -}
    • removedOutput schema / properties / truncated
      Removed value: -{
      -  "description": "Truncated?",
      -  "type": "boolean"
      -}
    • changedOutput schema / required
      Previous value: -[
      -  "ok"
      -]New value: +[
      +  "results",
      +  "summary"
      +]
  6. Addedv1.15.3
  7. Removedv1.15.0
  8. First observed

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral value beyond that: images and audio come back as media, other binaries require binary: true and return as a base64 embedded resource, and binary reads are full reads only. Return-format behavior is exactly what an agent needs before calling.

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?

Two sentences, no waste, front-loaded with the primary whole-file behavior before the mode and media qualifiers. Every clause carries information an agent needs.

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

Completeness5/5

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

For an 8-parameter, annotation-backed tool with no output schema, the description covers the decision-relevant surface: text vs image/audio vs other binary, whole vs slice, and the full-read restriction on binary. Remaining details (batch paths, hash option) are adequately documented in the schema itself.

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 description coverage is 100%, so the baseline is 3 and the schema carries per-parameter meaning. The description adds semantics the schema does not spell out: that the slice parameters select 'one slice' (implying they are alternatives, not combinable) and that binary is incompatible with slicing. It does not touch path/paths batch semantics or includeHash, which the schema covers.

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?

States a specific verb and resource ('Read text files, like cat') and enumerates the three read modes plus media/binary handling, so an agent immediately knows this is a content-retrieval tool distinct from list, stat, or search_text. It stops short of naming any sibling explicitly, so differentiation is inferred from function rather than stated.

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

Usage Guidelines4/5

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

Gives clear selection context for modes: whole read by default, one slice via head, tail, or startLine/endLine, and binary: true only for non-media binaries. It does not state when to prefer this over siblings like search_text or find_files, nor any exclusion conditions, so it is clear context without routing guidance.

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