show_file_excerpt

Show the content of a public text file inline in the chat.

show_file_excerpt

Shows the content of a public text file inline in the chat bubble. Use when a user asks to see file contents, or when the agent wants to quote a specific section of a document.

Only works for text-based files (.txt, .md, .csv, .json, .yaml, .xml, .html, etc.). For binary files, use present_public_file instead.

Parameters

Name	Type	Required	Description
filename	string	yes	Exact filename of the public file to read.
start_line	integer (≥1)	no	Line number to start from (1-based). Defaults to 1.
end_line	integer (≥1)	no	Line number to end at (inclusive). Defaults to start_line + 49 (50 lines).

Returns

{
  "action": "excerpt",
  "filename": "changelog.md",
  "content": "## v2.4.1 — 2026-05-19\n- Fixed CSV export date format\n- ...",
  "totalLines": 312,
  "startLine": 1,
  "endLine": 50
}

On failure (file not in manifest, binary extension, or read error):

{
  "error": "show_file_excerpt failed: binary file type.",
  "details": {
    "filename": "logo.png",
    "rejection_reason": "binary extension",
    "suggested_tool": "show_image",
    "hint": "Use show_image for .png files."
  }
}

---

Examples

Show the first 50 lines (default)

{ "filename": "faq.md" }

Show a specific section

{
  "filename": "changelog.md",
  "start_line": 1,
  "end_line": 30
}

Show a specific CSV section

Show the header row plus rows 1–9 of a CSV:

{
  "filename": "orders.csv",
  "start_line": 1,
  "end_line": 10
}

Page through a large file (custom tool)

export async function handle(input, ctx) {
  const pageSize  = 50;
  const page      = input.page ?? 1;
  const startLine = (page - 1) * pageSize + 1;
  const endLine   = page * pageSize;

  const result = await ctx.tools.show_file_excerpt({
    filename:   input.filename,
    start_line: startLine,
    end_line:   endLine,
  });

  return {
    page,
    total_lines: result.totalLines,
    total_pages: Math.ceil(result.totalLines / pageSize),
    content:     result.content,
  };
}

---

Call from your own custom tool

export async function handle(input, ctx) {
  return await ctx.tools.show_file_excerpt({
    filename:   input.doc,
    start_line: input.from_line ?? 1,
    end_line:   input.to_line,
  });
}

async def handle(input, ctx):
    return await ctx.tools.show_file_excerpt({
        'filename':   input['doc'],
        'start_line': input.get('from_line', 1),
        'end_line':   input.get('to_line'),
    })

Notes

• Only registered when the agent has public files.
• Binary extensions (.pdf, .png, .jpg, .docx, .xlsx, archives, etc.) are rejected with a suggested_tool hint.
• To offer the full file as a download instead of showing it inline, use present_public_file.