Tools

The three layers

Before using these tools it helps to be clear on the separation, because it is the source of almost every mistake:

1. The workspace catalog — everything that exists and can be used. list_workspace_tools.
2. The agent connection — what lets a specific agent call a tool. connect_agent_tool.
3. The connectors — what creates catalog entries. connect_mcp_server and create_api_tool.

Installing a tool in the workspace does not give it to any agent. Disconnecting it from an agent does not remove it from the workspace.

connect_mcp_server        → the server and its tools land in the catalog
list_workspace_tools      → you get the toolIds
connect_agent_tool        → the agent can now call them

Full REST documentation at Tools .

Workspace catalog

list_workspace_tools

Returns each tool's id (the toolId), name, description, kind, parameters and origin.

get_workspace_tool

Same as a list item, with the full parameter JSON Schema.

Agent tools

list_agent_tools

Only connections with status: "active" are passed to the model at runtime. An entry with toolExists: false is an orphaned connection: the catalog tool was deleted.

list_available_agent_tools

Returns the full catalog with isConnected and connectionStatus. Use it before connecting to avoid a 409.

connect_agent_tool

Returns 409 if it was already connected — use update_agent_tool_status in that case.

update_agent_tool_status

Deactivating is the reversible way to take a tool away from an agent. Activating one that was not connected connects it, so the tool is idempotent.

disconnect_agent_tool

Removes the connection. Does not delete the catalog tool or affect other agents.

MCP servers

preview_mcp_server

Connects to the server and lists its tools without saving anything. Call it before connect_mcp_server.

auth shapes:

The name values it returns are the server's original names: those are what you pass as tools to connect_mcp_server and sync_mcp_server_tools.

list_mcp_servers

status can be connected, pending_auth, needs_reauth or error. Credentials are never returned.

get_mcp_server

Includes discoveredTools (what the server offers, with an installed flag) and installedTools (what is in the catalog, with each toolId).

connect_mcp_server

{
  "name": "connect_mcp_server",
  "arguments": {
    "name": "Linear",
    "url": "https://mcp.linear.app/mcp",
    "auth": { "type": "bearer", "token": "lin_api_xxx" },
    "tools": ["create_issue", "search_issues"]
  }
}

Returns installedToolIds, ready to pass to connect_agent_tool.

refresh_mcp_server

Re-discovers tools and updates the schemas of installed ones. It does not install new ones: they show up with installed: false until you add them with sync_mcp_server_tools.

start_mcp_server_oauth

Returns authorizeUrl; a person must open it in a browser. The callback stores encrypted tokens.

sync_mcp_server_tools

delete_mcp_server

Removes the server, its credentials, its tools, and any connections those tools had with any agent.

Custom APIs

A custom API turns an HTTP endpoint into a tool. It has two parts: request describes the call with {{name}} placeholders, and variables declares who fills each one.

The schema the model sees is derived from the ai variables at enable time. That is why each variable's description is mandatory: it is what the model reads.

Lifecycle: draft → enabled → paused. Only enabled exists in the catalog.

list_api_tools

get_api_tool

Credentials and write-only constants are returned as "[REDACTED]"; they never enter the model context.

create_api_tool

{
  "name": "create_api_tool",
  "arguments": {
    "name": "order_lookup",
    "description": "Look up an order status by its reference. Use it when the customer asks where their order is.",
    "request": {
      "method": "GET",
      "url": "https://api.store.com/orders/{{orderId}}",
      "auth": { "type": "bearer", "token": "sk_live_xxx" }
    },
    "variables": [
      {
        "name": "orderId",
        "type": "string",
        "description": "Order reference, as shown in the confirmation email.",
        "required": true
      }
    ]
  }
}

It starts as a draft. Test it with test_api_tool and publish it with enable_api_tool.

update_api_tool

Same fields as create_api_tool but all optional, plus integrationId. Arrays (variables, request.headers, request.params) are replaced wholesale, not merged element by element.

test_api_tool

Start with dryRun: true to check the substitutions before hitting the real API. A failure from the remote API is not a tool error: it is reported in data.outcome and data.httpStatus.

enable_api_tool

Publishes the tool to the catalog and returns the toolId for connect_agent_tool. Fails with 400 if a model-facing variable has no description.

pause_api_tool

Withdraws the tool from the catalog, keeping its configuration.

delete_api_tool

Deletes the tool permanently. If you only want to switch it off, use pause_api_tool.

REST endpoints with no MCP tool

• Installing first-party apps (kind: "integration") is done from the dashboard. Once installed, their tools show up in list_workspace_tools and connect like any other.