Skip to content
All tools

file_read

Files & Finder · macOS · Windows

Effect: read (strongest supported action). Status: gated.

Gated means the tool requires an installed app, a connected account, permission, or runtime availability. Check those requirements on the listed platform before using it.

macOS

Purpose

Reads a plain text file from the local filesystem by its absolute path — the primary, default tool for reading a local text file (use this unless the file is a PDF, Word, Excel, or PowerPoint document, which have their own readers). Reads anywhere on this Mac — home, external disks, cloud drives, /tmp — with one exception: credential and identity locations (keychains, ~/.ssh, ~/.aws, browser logins, another user's home, Time Machine backups) are never read. Supports .txt, .md, .csv, .json, .xml, .log, .yaml, .toml and common code file types; auto-detects UTF-8 with Latin-1/Windows-1252 fallback. For files in OneDrive use onedrive_read_file, in Google Drive gdrive_read_file; for PDFs pdf_read, Word word_read, Excel excel_read.

Required inputs

Permissions and confirmation

No explicit confirmation parameter is exposed in this snapshot. This does not grant permission to act: obtain user authorization before any real action.

Full input schema — macOS
{
  "properties": {
    "force_download": {
      "description": "If the file is stored in the cloud and evicted from this Mac (dataless), request the download and wait for it instead of failing. Off by default: a download can take minutes and use metered data, so it is the caller's decision.",
      "type": "boolean"
    },
    "max_bytes": {
      "description": "Maximum bytes to read (default 256 KB, max 2 MB). A longer file comes back with truncated=true and next_offset: pass next_offset as offset to continue.",
      "type": "integer"
    },
    "offset": {
      "description": "Start reading at this byte offset (default 0)",
      "type": "integer"
    },
    "path": {
      "description": "Absolute path to the file",
      "type": "string"
    }
  },
  "required": [
    "path"
  ],
  "type": "object"
}

Documentation example

Do not execute this example. These concrete inputs refer to a fictional demonstration dataset. Resolve real handles and obtain user authorization before any real call.

{
  "path": "/Users/demo/Documents/meeting-notes.txt"
}

Windows

Purpose

Reads a plain-text file from the local filesystem by its absolute path — the default tool for reading a local text file (use pdf_read/word_read/excel_read/ppt_read for those document types, onedrive_read_file / gdrive_read_file for cloud storage). Reads anywhere on this PC, except credential and identity locations (browser logins, SSH and cloud keys, Windows credential stores, another user's profile), which are never read. Supports offset/max_bytes for chunked reads of large files: a cut read says truncated=true and next_offset, the offset to read on from.

Required inputs

Permissions and confirmation

No explicit confirmation parameter is exposed in this snapshot. This does not grant permission to act: obtain user authorization before any real action.

Full input schema — Windows
{
  "properties": {
    "force_download": {
      "description": "For a cloud placeholder (OneDrive online-only) bigger than 25 MB: download it and wait up to 60 s. Smaller ones are downloaded on their own.",
      "type": "boolean"
    },
    "max_bytes": {
      "description": "Maximum bytes to read (default 256 KB, max 2 MB). A cut read says next_offset.",
      "type": "integer"
    },
    "offset": {
      "description": "Start reading at this byte offset (default 0).",
      "type": "integer"
    },
    "path": {
      "description": "Absolute path to the file (a leading ~ is expanded).",
      "type": "string"
    }
  },
  "required": [
    "path"
  ],
  "type": "object"
}

Documentation example

Do not execute this example. These concrete inputs refer to a fictional demonstration dataset. Resolve real handles and obtain user authorization before any real call.

{
  "path": "C:\\Users\\demo\\Documents\\meeting-notes.txt"
}