Tools
| Tool | Description |
|---|---|
write_artifact | Create a downloadable file from text content |
write_artifact_from_url | Create a downloadable file by fetching from a URL |
read_artifact | Read content from an artifact by file ID (supports smart reading options) |
list_artifacts | List all artifact files in the current chat session |
write_artifact
Create a downloadable file from text content. Use when the user explicitly requests “save as”, “export”, “create file”, or when generating code files. Parameters:| Parameter | Type | Required | Description |
|---|---|---|---|
filename | string | Yes | Name of the file with extension (e.g. "data.csv") |
content | string | Yes | The file content as a string |
fileType | string | Yes | File extension/type: csv, json, txt, md, html, js, ts, py |
| Field | Type | Description |
|---|---|---|
success | boolean | Whether the artifact was created |
filename | string | Name of the created file |
url | string | Download URL for the file |
id | string | File ID (for referencing in read_artifact) |
mimeType | string | MIME type of the file |
size | number | File size in bytes |
write_artifact_from_url
Create a downloadable file by fetching content from a URL. Use when you have a download URL from another tool (e.g., OneDrive, Google Drive, Slack) and want to save it as an artifact. The content is fetched server-side and never enters the agent’s context, making it efficient for large files. Parameters:| Parameter | Type | Required | Description |
|---|---|---|---|
sourceUrl | string | Yes | The URL to fetch the file content from |
filename | string | Yes | Name for the artifact file with extension (e.g. "report.pdf", "data.xlsx") |
authHeaders | object | No | Optional authentication headers to include when fetching from the source URL |
| Field | Type | Description |
|---|---|---|
success | boolean | Whether the artifact was created |
filename | string | Name of the created file |
url | string | Download URL for the file |
id | string | File ID |
mimeType | string | MIME type of the file |
size | number | File size in bytes |
read_artifact
Retrieve content from an artifact file by its ID. Use when a tool result shows_artifact.truncated: true to get the full data. Supports selective reading to avoid fetching entire large files.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
file_id | string | Yes | The file ID of the artifact to read (e.g., _artifact.id from a truncated result) |
search | string | No | Search pattern to find in the content (case-insensitive). Returns matching lines with context. |
context_lines | number | No | Number of lines to show before and after each search match (default: 2) |
start_line | number | No | Start line number for line range extraction (1-indexed, inclusive) |
end_line | number | No | End line number for line range extraction (1-indexed, inclusive) |
json_path | string | No | Dot notation path to extract from JSON content (e.g. "data.items", "results[0]") |
array_indices | string | No | Comma-separated indices or ranges to extract from array content (e.g. "0,1,2" or "0-5") |
| Field | Type | Description |
|---|---|---|
success | boolean | Whether the read succeeded |
content | string | File content (full or extracted) |
size | number | File size in bytes |
filename | string | File name |
mimeType | string | MIME type |
mode | string | When using smart options: search, line_range, json_path, or array_indices |
list_artifacts
List all artifact files in the current chat session. Returns file names, IDs, sizes, MIME types, and creation dates. Parameters:| Parameter | Type | Required | Description |
|---|---|---|---|
filter_type | string | No | Filter by MIME type prefix (e.g. "text/", "application/json", "image/") |
filter_name | string | No | Filter by filename pattern (case-insensitive substring match) |
| Field | Type | Description |
|---|---|---|
success | boolean | Whether the list succeeded |
totalCount | number | Total number of artifacts |
filteredCount | number | Number after applying filters |
artifacts | object[] | Array of artifact objects |
artifacts[].id | string | File ID |
artifacts[].filename | string | File name |
artifacts[].mimeType | string | MIME type |
artifacts[].size | number | File size in bytes |
artifacts[].sizeFormatted | string | Human-readable size (e.g. “1.2 MB”) |
artifacts[].createdAt | string | Creation timestamp |