/gateway | Type: Embedded | PCID required: No
Tools
| Tool | Description |
|---|---|
gateway_write_artifact | Create a downloadable file (CSV, JSON, TXT, MD, HTML, JS, TS, PY) stored as an artifact. If chatId is not provided, a new chat is auto-created as a storage bucket and its ID is returned. |
gateway_write_artifact_from_url | Create a downloadable file by fetching content from a URL. The content is fetched server-side. If chatId is not provided, a new chat is auto-created as a storage bucket and its ID is returned. |
gateway_read_artifact | Read content from an artifact file by its ID. Supports smart extraction via natural language query, grep-like search, line ranges, JSON path extraction, and pagination for large files. |
gateway_list_artifacts | List all artifact files in a chat. Returns file names, IDs, sizes, MIME types, and creation dates. |
gateway_list_workspace | List all connections and resources in the user’s workspace (connections, datastores, filestores, knowledge bases, vaults). Returns every item with its ID (PCID for connections, collectionId for resources) and name. |
capabilities_discover for task-relevant work — that tool returns IDs inline for recommended items and is more efficient. Use gateway_list_workspace only when:
- You need to enumerate everything independent of a task (e.g., “show me all my connections”)
- The user has multiple connections for the same service and you need to see all of them to disambiguate (e.g., “which Gmail should I use?”)
capabilities_discoverreturnedalternativesAvailableand you want to show alternatives to the user | |gateway_invoke| Invoke a single MCP tool on a registered server. Good for simple, one-shot tool calls.
- Connections are auto-injected. If the user has one connection for a service (e.g., one Gmail account), it is used automatically — do NOT pass PCID.
- If the user has MULTIPLE connections for the same service, pass PCID to select which one. Discover available connections and their PCIDs via capabilities_discover with types: [“connection”].
- Do NOT pass PCID in the “arguments” object — use the top-level PCID parameter instead.
capabilities_discover | Discover available capabilities for a task. Returns lightweight recommendations for tools, agent skills, connections, and/or resources. Call capability_details to get full details for selected items. Use the “types” parameter to filter by capability type.
GATEWAY USAGE:
- To find available connections and their PCIDs: call with types: [“connection”] and a request describing the service (e.g., “gmail connections”).
- To find available tools: call with types: [“tool”] and a request describing what you want to do.
- Returns IDs inline for every recommended item (PCIDs for connections, collectionIds for resources) — you do NOT need to call gateway_list_workspace afterward to get IDs.
- If the response includes
alternativesAvailable(e.g.,{"gmail": 2}), the user has multiple connections for that service and only one was picked. Call gateway_list_workspace to see all options when the user needs to choose. | |capability_details| Get full details for selected capabilities. For tools: returns inputSchema (full JSON Schema with nested objects, arrays, enums, and required fields), outputSchema, isDynamic (true for dynamic MCP servers), and any matching agent skill content. For agent skills: returns full knowledge content. For connections: returns connection metadata. For resources: returns collection details. Use the “types” parameter to filter by capability type. For custom integrations, when capabilities_discover returns a tool name like “myintegration_c_request”, pass ONLY that exact tool name to capability_details (not the integration name or skill name). The response automatically includes all associated content including skill instructions. | |code-execution_execute| Execute JavaScript code in a sandboxed VM with access to MCP tools and file helpers.
- callTool(serverPath, toolName, toolArgs) — Call a configured MCP tool via HTTP. DO NOT pass PCID — connection is auto-injected from selection context.
- codeExec.createArtifact(filename, content, fileType) — Create a file (uploads to platform, returns { success, id, url, filename, mimeType, size }). Supported types: csv, txt, json, html, xml, js, ts, md, py. This is a simplified file helper — for full artifact features, use the agent’s write_artifact tool.
- codeExec.readArtifact(identifier) — Read a file by ID, filename, or URL (returns { success, content, size, filename, mimeType }). This is a simplified reader — for advanced features (search, pagination, smartGrepQuery), use the agent’s read_artifact tool after code execution returns.
- console.log/error/warn(…args) — Captured to logs array returned in the response.
- setTimeout/setInterval/clearTimeout/clearInterval — Standard timer functions (cleaned up after execution).
${e.from},${e.subject}).join(‘\n’);
await codeExec.createArtifact(‘emails.csv’, csv, ‘csv’);
// Read an artifact from the conversation:
const data = await codeExec.readArtifact(‘file_abc123’);
console.log(data.content);
// Return result to agent:
return { count: emails.length };
LARGE RESULTS: If the returned value serializes to >200 bytes, an artifact is created automatically and the response includes an artifactId with a truncated preview. The agent can use read_artifact to access the full result.
IMPORTANT — NO UNBOUNDED LOOPS:
- NEVER write while(true), while(hasMore), or open-ended loops that call callTool() repeatedly. Each callTool() is an HTTP round-trip and loops will timeout.
- If a tool doesn’t have a pagination parameter (e.g. “page”), do NOT attempt manual pagination — you will get the same page repeatedly.
- If you need more data than one API call returns, return what you have and tell the user the tool’s page limit was reached.
- Bounded loops (e.g. for(let i=0; i<items.length; i++)) over local data are fine.
- Be suspicious of round numbers (30, 50, 100) — they usually mean you hit a perPage limit, not the actual total.
- If the user has one connection per service, it is used automatically.
- If the user has multiple connections for the same service, use the connectionSelections parameter to specify which one: {“gmail”: “<pcid>”}. Obtain PCIDs via capabilities_discover with types: [“connection”].
- When connectionSelections is omitted, the first connection per service is used as default. |
gateway_write_artifact
Create a downloadable file (CSV, JSON, TXT, MD, HTML, JS, TS, PY) stored as an artifact. If chatId is not provided, a new chat is auto-created as a storage bucket and its ID is returned. Parameters:| Parameter | Type | Required | Default | 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 |
chatId | string | No | — | Chat ID to store the artifact in. If omitted, a new chat is created automatically. |
agentId | string | No | — | Agent ID for auto-creating a chat. Defaults to “system-coworker-agent”. Only used when chatId is not provided. |
gateway_write_artifact_from_url
Create a downloadable file by fetching content from a URL. The content is fetched server-side. If chatId is not provided, a new chat is auto-created as a storage bucket and its ID is returned. Parameters:| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
sourceUrl | string | Yes | — | The URL to fetch the file content from (e.g., a download URL from OneDrive or Google Drive) |
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 |
chatId | string | No | — | Chat ID to store the artifact in. If omitted, a new chat is created automatically. |
agentId | string | No | — | Agent ID for auto-creating a chat. Defaults to “system-coworker-agent”. Only used when chatId is not provided. |
gateway_read_artifact
Read content from an artifact file by its ID. Supports smart extraction via natural language query, grep-like search, line ranges, JSON path extraction, and pagination for large files. Parameters:| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
file_id | string | Yes | — | The file ID of the artifact to read |
chatId | string | Yes | — | Chat ID where the artifact is stored |
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). |
smartGrepQuery | string | No | — | Natural language query for LLM-powered extraction (e.g., “list all names and emails as a table”) |
search | string | No | — | Search pattern to find in the content (case-insensitive). Returns matching lines with context. |
context_lines | number | No | — | Number of context lines around each search match (default: 2) |
start_line | number | No | — | Start line number for line range extraction (1-indexed) |
end_line | number | No | — | End line number for line range extraction (1-indexed) |
json_path | string | No | — | Dot notation path to extract from JSON (e.g., “data.items”, “results[0]“) |
array_indices | string | No | — | Comma-separated indices or ranges (e.g., “0,1,2” or “0-5”) |
gateway_list_artifacts
List all artifact files in a chat. Returns file names, IDs, sizes, MIME types, and creation dates. Parameters:| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
chatId | string | Yes | — | Chat ID to list artifacts from |
filter_type | string | No | — | Filter by MIME type prefix (e.g., “text/”, “application/json”) |
filter_name | string | No | — | Filter by filename pattern (case-insensitive substring match) |
gateway_list_workspace
List all connections and resources in the user’s workspace (connections, datastores, filestores, knowledge bases, vaults). Returns every item with its ID (PCID for connections, collectionId for resources) and name. Prefercapabilities_discover for task-relevant work — that tool returns IDs inline for recommended items and is more efficient. Use gateway_list_workspace only when:
- You need to enumerate everything independent of a task (e.g., “show me all my connections”)
- The user has multiple connections for the same service and you need to see all of them to disambiguate (e.g., “which Gmail should I use?”)
capabilities_discoverreturnedalternativesAvailableand you want to show alternatives to the user
gateway_invoke
Invoke a single MCP tool on a registered server. Good for simple, one-shot tool calls. NOTE: Results are returned in full (not truncated). This is fine for most calls, but if a tool is likely to return a large amount of data (e.g., searching hundreds of emails, bulk exports, large query results), prefer code-execution_execute instead — it automatically saves large results as artifacts. CONNECTION HANDLING:- Connections are auto-injected. If the user has one connection for a service (e.g., one Gmail account), it is used automatically — do NOT pass PCID.
- If the user has MULTIPLE connections for the same service, pass PCID to select which one. Discover available connections and their PCIDs via capabilities_discover with types: [“connection”].
- Do NOT pass PCID in the “arguments” object — use the top-level PCID parameter instead.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
server | string | Yes | — | Server name or path (e.g., “gmail”, “slack”, “dynamic/amplitude”, “remote/linear-official-mcp”). Use capability_details to find exact server names and tool schemas. |
tool | string | Yes | — | The tool name to call (e.g., “gmail_search_emails”, “slack_send_message”). Use capability_details to find exact tool names and their required arguments. |
arguments | object | No | {} | Tool arguments as key-value pairs. Do NOT include PCID here — use the top-level PCID parameter instead. |
capabilities_discover
Discover available capabilities for a task. Returns lightweight recommendations for tools, agent skills, connections, and/or resources. Call capability_details to get full details for selected items. Use the “types” parameter to filter by capability type. GATEWAY USAGE:- To find available connections and their PCIDs: call with types: [“connection”] and a request describing the service (e.g., “gmail connections”).
- To find available tools: call with types: [“tool”] and a request describing what you want to do.
- Returns IDs inline for every recommended item (PCIDs for connections, collectionIds for resources) — you do NOT need to call gateway_list_workspace afterward to get IDs.
- If the response includes
alternativesAvailable(e.g.,{"gmail": 2}), the user has multiple connections for that service and only one was picked. Call gateway_list_workspace to see all options when the user needs to choose.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
request | string | Yes | — | Natural language description of the task (e.g., “process vendor invoices”, “create HTML dashboard”, “send email with attachments”). |
types | string[] | No | — | Filter results to specific capability types. If omitted, returns all types. Examples: [“connection”] for connections only, [“resource”] for resources only, [“tool”, “agentSkill”] for tools and skills only. |
context | string | No | — | Skill context filter. Use “workflow-creation” if you are the Agent Mode Workflow Builder (building or editing workflows). Use “agent-execution” for all other agents executing tasks. If omitted, returns all skills. |
bypassCache | boolean | No | — | Bypass internal caches (for testing). |
debug | boolean | No | — | Include LLM prompts in _metadata (for integration test debugging). |
capability_details
Get full details for selected capabilities. For tools: returns inputSchema (full JSON Schema with nested objects, arrays, enums, and required fields), outputSchema, isDynamic (true for dynamic MCP servers), and any matching agent skill content. For agent skills: returns full knowledge content. For connections: returns connection metadata. For resources: returns collection details. Use the “types” parameter to filter by capability type. For custom integrations, when capabilities_discover returns a tool name like “myintegration_c_request”, pass ONLY that exact tool name to capability_details (not the integration name or skill name). The response automatically includes all associated content including skill instructions. Parameters:| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
items | string[] | Yes | — | Names/IDs of capabilities to get details for (e.g., [“google-drive”, “invoice-processing”, “html-creation”, “My Google Drive Connection”, “sales”]). Use exact tool names returned from capabilities_discover. |
types | string[] | No | — | Filter results to specific capability types. If omitted, searches all types. Examples: [“connection”] for connections only, [“resource”] for resources only. |
code-execution_execute
Execute JavaScript code in a sandboxed VM with access to MCP tools and file helpers. Available globals:- callTool(serverPath, toolName, toolArgs) — Call a configured MCP tool via HTTP. DO NOT pass PCID — connection is auto-injected from selection context.
- codeExec.createArtifact(filename, content, fileType) — Create a file (uploads to platform, returns { success, id, url, filename, mimeType, size }). Supported types: csv, txt, json, html, xml, js, ts, md, py. This is a simplified file helper — for full artifact features, use the agent’s write_artifact tool.
- codeExec.readArtifact(identifier) — Read a file by ID, filename, or URL (returns { success, content, size, filename, mimeType }). This is a simplified reader — for advanced features (search, pagination, smartGrepQuery), use the agent’s read_artifact tool after code execution returns.
- console.log/error/warn(…args) — Captured to logs array returned in the response.
- setTimeout/setInterval/clearTimeout/clearInterval — Standard timer functions (cleaned up after execution).
${e.from},${e.subject}).join(‘\n’);
await codeExec.createArtifact(‘emails.csv’, csv, ‘csv’);
// Read an artifact from the conversation:
const data = await codeExec.readArtifact(‘file_abc123’);
console.log(data.content);
// Return result to agent:
return { count: emails.length };
LARGE RESULTS: If the returned value serializes to >200 bytes, an artifact is created automatically and the response includes an artifactId with a truncated preview. The agent can use read_artifact to access the full result.
IMPORTANT — NO UNBOUNDED LOOPS:
- NEVER write while(true), while(hasMore), or open-ended loops that call callTool() repeatedly. Each callTool() is an HTTP round-trip and loops will timeout.
- If a tool doesn’t have a pagination parameter (e.g. “page”), do NOT attempt manual pagination — you will get the same page repeatedly.
- If you need more data than one API call returns, return what you have and tell the user the tool’s page limit was reached.
- Bounded loops (e.g. for(let i=0; i<items.length; i++)) over local data are fine.
- Be suspicious of round numbers (30, 50, 100) — they usually mean you hit a perPage limit, not the actual total.
- If the user has one connection per service, it is used automatically.
- If the user has multiple connections for the same service, use the connectionSelections parameter to specify which one: {“gmail”: “<pcid>”}. Obtain PCIDs via capabilities_discover with types: [“connection”].
- When connectionSelections is omitted, the first connection per service is used as default.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
code | string | Yes | — | JavaScript code to execute in the sandbox. |
timeout | number | No | 600000 | Timeout in milliseconds (default: 600000 = 10 minutes, min: 1000 = 1 second, max: 900000 = 15 minutes) |
| connectionSelections | object | No | — | Optional mapping of service key to PCID for callTool() connection injection. Use this when the user has multiple connections for the same service and you need to select a specific one. Keys are service names (e.g., “gmail”, “slack”), values are PCIDs obtained from capabilities_discover. When omitted, connections are auto-selected (first connection per service). Code should NOT contain PCIDs — pass them here instead so code remains portable across users. |

