agent_invoke | Invoke an agent and get its response. Use this to leverage agent capabilities for data processing, decision making, or complex tasks. The agent can be invoked with a message and optionally continue a conversation using chatId. Returns the agent’s response, chatId for continuing conversations, and agentId. |
capabilities_discover | Discover available capabilities for a task. Returns lightweight recommendations for tools, agent skills, connections, and/or resources — and, opt-in, invocable workflows and agents. 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.
- To discover invocable workflows/agents (OPT-IN — off by default): call with types: [“workflow”, “agent”]. Each result carries its invoke handle (automationId / agentId); invoke them via workflow_invoke / agent_invoke.
- 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.
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).
EXAMPLES:
// Call MCP tools (DO NOT pass PCID - connection is auto-injected from selection context):
const emails = await callTool(“gmail”, “gmail_search_emails”, {
query: “is:unread”
});
// Create output files:
const csv = emails.map(e => ${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.
Default timeout: 10 minutes (max 15 minutes).
GATEWAY CONNECTION HANDLING:
Connections are auto-injected for all callTool() calls inside the sandbox — do NOT put PCIDs in the code.
- 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_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.
For complex multi-step operations, data processing, file creation, or tool calls expected to return large results, use code-execution_execute instead. |
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.
Prefer capabilities_discover for task-relevant work — that tool returns IDs inline for recommended items and is more efficient. Use gateway_list_workspace only when:
1. You need to enumerate everything independent of a task (e.g., “show me all my connections”)
2. 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?“)
3. capabilities_discover returned alternativesAvailable and you want to show alternatives to the user |
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_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. |
workflow_invoke | Invoke a workflow by its automation ID and return its results. Runs the workflow’s latest published release under your identity — you can only invoke workflows you already have access to. Use the automationId returned by capabilities_discover (call it with types: [“workflow”] to discover invocable workflows). Long-running workflows are handled by the async execution system. |
