Files in tool calls

Tools often need to work with files: a function that returns a chart, a code-execution run that writes a CSV, an MCP server that hands back a PDF. This page covers how files move in and out of tool calls.

Returning images and documents from your own tools

A function tool result can carry content parts, not just a string. Images and documents in a tool result are shown to the model the same way as in a user message.

{
  "role": "tool",
  "tool_call_id": "call_4",
  "content": [
    { "type": "text", "text": "Revenue by month, 2026." },
    { "type": "image_url", "image_url": { "url": "data:image/png;base64,iVBORw0KGgo…" } }
  ]
}

Prefer a file part with a file_id when the same file appears in many turns; the bytes are then sent once.

{ "type": "file", "file": { "file_id": "file_01JC3D5F7H9K1M3P5R7T" } }

Files for code execution

Files you mention in the request are mounted into the code-execution container under /mnt/inputs/ with their original names. Files the code writes to /mnt/outputs/ are uploaded to the Files API automatically when the request ends and listed in the tool result:

{
  "type": "syntic_code_execution_result",
  "stdout": "Wrote 14 rows",
  "output_files": [{ "file_id": "file_01JD…", "filename": "mismatches.csv", "bytes": 1820 }]
}

Download them with file content. Output files have purpose: "tool_output" and expire after 30 days unless you change expires_at.

Files and MCP servers

When an MCP tool returns an embedded resource or an image, the connector turns it into the matching content part for the model. Resources over 10 MB are stored as a file instead and the model receives a short text note with the file_id, so it can mention or pass it on without the bytes filling the context.

Limits

Billing

Images and documents in tool results are billed as input tokens on the next model call, like any other input. Uploading output files is free; storage counts toward the workspace’s file quota.