artifact-tools

Built-in agent tools for creating, reading, and listing downloadable files

Type: Agent Built-in | Server path: N/A | PCID required: No

Built-in and always available to agents (but not available via API). These tools are part of the agent runtime — no MCP server configuration or setup required. They are automatically available to every Claude and GPT agent. Unlike MCP server tools, artifact tools cannot be invoked directly via the API; they are only used by agents during conversation to create downloadable files, read truncated results, and list artifacts.

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 — supports LLM-powered smart extraction and pagination
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

Response fields:

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

Response fields:

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

Note: URL fetches are subject to SSRF protection. Localhost and private IP URLs are blocked. Maximum download size is 100MB.

---

read_artifact

Read content from an artifact file. Use when a tool result shows _artifact.truncated: true to get the full data.

The recommended approach is smartGrepQuery — describe what you need in natural language and a fast LLM extracts it from the file. Think of it like grep on steroids: ask for specific fields, filters, summaries, counts, or formatted output. You can iterate by reading the first chunk, refining your query, and continuing with offset.

For binary files (XLSX, PDF), use _textArtifact.id instead of _artifact.id if a _textArtifact field is present.

Parameters:

Parameter	Type	Required	Default	Description
file_id	string	Yes	—	The file ID of the artifact to read (e.g., _artifact.id from a truncated result)
smartGrepQuery	string	No	—	Natural language query — a fast LLM extracts exactly what you ask for. Examples: "list all names and emails as a table", "count items by status", "grep -i error", "summarize the key findings"
offset	number	No	—	Character offset to start from. Use nextOffset from a previous response to continue reading.
limit	number	No	—	Max characters per call. Default: 10K (raw) or 100K (smartGrepQuery). Set to totalSize for files under 200K to process in one call.
search	string	No	—	Search pattern to find in the content (case-insensitive). Returns matching lines with context.
context_lines	number	No	2	Number of lines to show before and after each search match
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")

When the response includes hasMore: true, you have only seen partial data. Call read_artifact again with offset set to nextOffset (and the same smartGrepQuery) to get the rest. Do not treat partial results as final.

Response fields:

Field	Type	Description
success	boolean	Whether the read succeeded
content	string	File content (full or extracted)
totalSize	number	Total file size in characters
size	number	File size in bytes
filename	string	File name
mimeType	string	MIME type
hasMore	boolean	Whether more content is available (paginate with offset/nextOffset)
nextOffset	number	Character offset for the next page (use as offset in follow-up call)
mode	string	Reading mode used: smartGrepQuery, 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)

Response fields:

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