> ## Documentation Index > Fetch the complete documentation index at: https://docs.pinkfish.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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`](#write_artifact) | Create a downloadable file from text content | | [`write_artifact_from_url`](#write_artifact_from_url) | Create a downloadable file by fetching from a URL | | [`read_artifact`](#read_artifact) | Read content from an artifact — supports LLM-powered smart extraction and pagination | | [`list_artifacts`](#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 |