> ## Documentation Index
> Fetch the complete documentation index at: https://hexelstudio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool Gateway

> Connect agents to external systems with managed credentials and execution.

The Tool Gateway lets your agents take actions in external systems (send an email via Gmail, open a GitHub issue, post a Slack message, create a Jira ticket) without you handling OAuth flows or storing secrets in agent code. You connect a provider account once, bind the toolkit to an agent, and the gateway resolves credentials at execution time.

## Capabilities

<CardGroup cols={2}>
  <Card title="Tool Catalog" icon="grip" href="/docs/tool-gateway/catalog">
    Browse toolkits and discover available tools.
  </Card>

  <Card title="Connected Accounts" icon="link" href="/docs/tool-gateway/connected-accounts">
    Authorize providers with managed OAuth.
  </Card>

  <Card title="Bindings" icon="link-horizontal" href="/docs/tool-gateway/bindings">
    Grant agents access to specific toolkits.
  </Card>

  <Card title="Executing Tools" icon="play" href="/docs/tool-gateway/execution">
    Run tools synchronously, async, or in batches.
  </Card>

  <Card title="Triggers & Webhooks" icon="bolt" href="/docs/tool-gateway/triggers-and-webhooks">
    Automate tools on external events.
  </Card>

  <Card title="Workspace Groups" icon="lock" href="/docs/tool-gateway/workspace-groups">
    Control which tools are available where.
  </Card>

  <Card title="MCP" icon="cube" href="/docs/tool-gateway/mcp">
    Integrate Model Context Protocol servers.
  </Card>
</CardGroup>

## Available toolkits

| Toolkit         | Provider  |
| --------------- | --------- |
| `GMAIL`         | Google    |
| `GOOGLE_SHEETS` | Google    |
| `SLACK`         | Slack     |
| `GITHUB`        | GitHub    |
| `JIRA`          | Atlassian |
| `WHATSAPP`      | Meta      |

## How it works

```mermaid theme={"dark"}
flowchart LR
    A[Connect account<br/>OAuth] --> B[Bind toolkit<br/>to agent]
    B --> C[Discover tools]
    C --> D[Execute]
```

1. **Connect** a provider account via OAuth. Credentials are stored encrypted and never returned by the API.
2. **Bind** the toolkit to an agent, linking it to the connected account.
3. **Discover** available tools in scope.
4. **Execute** tools. The gateway resolves credentials automatically based on the agent's bindings.

## SDK access

<Tabs>
  <Tab title="Python">
    ```python theme={"dark"}
    from hexel import Hexel

    client = Hexel(api_key="YOUR_API_KEY")
    toolkits = client.tools.list_toolkits()
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={"dark"}
    import { Hexel } from "hexel-sdk";

    const client = new Hexel({ apiKey: "YOUR_API_KEY" });
    const toolkits = await client.orchestrator.tools.list();
    ```
  </Tab>

  <Tab title="curl">
    ```bash theme={"dark"}
    curl https://api.hexelstudio.com/tools/v1/toolkits \
      -H "Authorization: Bearer $TOKEN"
    ```
  </Tab>
</Tabs>

## Errors

Tool Gateway returns a JSON error body: `{ "error": { "code": "<CODE>", "message": "<human_message>" } }`.

| HTTP  | `code`            | When                                                                      |
| ----- | ----------------- | ------------------------------------------------------------------------- |
| `400` | `INVALID_REQUEST` | Missing or invalid fields (e.g. `tool_slug is required`).                 |
| `403` | —                 | Not permitted, or the tool isn't allowed by a workspace group.            |
| `404` | —                 | Tool, toolkit, connected account, or binding doesn't exist.               |
| `409` | —                 | Idempotency conflict — the same key was reused with different parameters. |
| `429` | —                 | Rate limit exceeded.                                                      |

## Rate limits

Tool execution is rate-limited at multiple levels: per organization, per toolkit, and per connected account. Provider-side limits also apply per tool. Exceeding any level returns `429`. Specific values depend on your plan and the provider — see the [Console](https://console.hexelstudio.com).

<Tip>
  Transient provider failures may fail fast and recover automatically, so a retry shortly after a `5xx` from a provider often succeeds.
</Tip>

## Security

| Concern       | How it's handled                                                                                                                               |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Credentials   | Connected-account credentials are encrypted at rest and never returned by the API. The gateway resolves them automatically at execution time.  |
| Authorization | Operations require RBAC permissions; available tools can be constrained per workspace with [workspace groups](/docs/tool-gateway/workspace-groups). |
| Scoping       | Connected accounts, bindings, and executions are scoped to your organization, workspace, and environment.                                      |

## Next steps

Start with the [Tool Catalog](/docs/tool-gateway/catalog) to see what is available.