Skip to main content

​
What it does

The Read File tool lets an agent open and read a single file from anywhere it already has access: a file in its Python sandbox, a conversation attachment (user-uploaded or tool-generated), a knowledge-base file, or a URL. It’s the agent equivalent of a coding assistant’s “Read” primitive — a safe, read-only way to pull a specific file into context on demand.
Read File is pre-checked when you create an agent in the Control Hub. It’s a read-only baseline that can only reach files the agent could already access, so new agents start with it enabled. It behaves like any other tool — you can uncheck it at any time. See Default-on tools.

​
Key features

  • Four sources, one tool — sandbox paths, attachment:<filename>, kb:<file_id>, and https://… URLs
  • Documents auto-extract to text — PDF, DOCX, XLSX, PPTX, CSV, EML, and MSG are converted automatically
  • Images come back as vision — PNG/JPG/GIF/WebP are returned as images the agent can visually analyze (charts, screenshots, diagrams, scans); oversized images are auto-downscaled
  • Line pagination — all text is paginated with offset/limit so large files never overflow context
  • KB chunk reads — for kb:<file_id>, read embedded knowledge-base chunks by chunkIndex from search results
  • PDF page images — read a PDF as page images (not just text) to reason over layout, charts, and scanned content

​
Parameters

​
Common use cases

​
Read a conversation attachment

Pull a file the user uploaded — or one an earlier tool generated — into the conversation as text.

​
Read a specific knowledge-base file

Open the full extracted text of a knowledge-base file by its file id, line-paginated.

​
Continue from a knowledge-base search result

Read embedded KB chunks starting at the chunkIndex returned by search_knowledge_base. This only applies to knowledge-base files.

​
Look at a PDF’s pages as images

Visually analyze charts, diagrams, layout, or scanned pages that text extraction can’t capture.

​
Read a sandbox file

Inspect a screenshot or file the agent produced in its sandbox — for example, checking a render screenshot before publishing an app.

​
Image support depends on the model

Returning an image from a tool requires a model whose provider can receive tool-result images as real vision:
  • Supported: Anthropic, OpenAI, Azure OpenAI, and Google (Gemini).
  • Text-only: xAI (Grok). On xAI, image requests are automatically downgraded to text (with a note), and image-only files return an error suggesting an Anthropic, OpenAI, Azure, or Google model.
Documents and plain text read the same on every model — only image/vision output is gated.

​
Limitations

  • Reads one file per call (use a separate call per file)
  • Very large images are rejected; oversized readable images are downscaled
  • Image and PDF-page-image output requires a vision-capable provider (see above)
  • Non-PDF Office documents (DOCX/XLSX/PPTX/CSV/email) are text-only — no page images
  • Scrape URL — extract content from web pages and PDFs by URL
  • Search Knowledge Base — semantic search across a knowledge base (vs. reading one known file)
  • Run Code — process files programmatically in the sandbox