> ## 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 Catalog

> Browse toolkits, discover tools, and understand the tool lifecycle.

Before you execute a tool, you need to discover what's available. The catalog is how you browse toolkits and find the right tool slug — for example, finding that "send an email via Gmail" maps to `GMAIL_SEND_EMAIL`. Once you know the slug, you can bind it to an agent and execute it.

The catalog is the set of tools available to your agents, organized into toolkits by provider. List toolkits, inspect individual tools, and discover what is available in a given scope.

## Key concepts

| Term          | Meaning                                               |
| ------------- | ----------------------------------------------------- |
| **Toolkit**   | A provider grouping of related tools (e.g. `GMAIL`).  |
| **Tool**      | A single callable action (e.g. `GMAIL_SEND_EMAIL`).   |
| **Slug**      | The `UPPER_CASE` identifier for a toolkit or tool.    |
| **Discovery** | Listing tools available to an agent in a given scope. |

## Available toolkits

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

## Browse the catalog

<Tabs>
  <Tab title="Python">
    ```python theme={"dark"}
    # List toolkits
    toolkits = client.tools.list_toolkits()

    # List tools in a toolkit
    tools = client.tools.list_tools(toolkit="GMAIL")

    # Get a single tool
    tool = client.tools.get_tool("GMAIL_SEND_EMAIL")

    # Discover tools available to an agent in scope
    available = client.tools.discover_tools(scope="agent")
    ```
  </Tab>

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

    curl "https://api.hexelstudio.com/tools/v1/tools?toolkit=GMAIL" \
      -H "Authorization: Bearer $TOKEN"

    curl "https://api.hexelstudio.com/tools/v1/tools/discover?scope=agent" \
      -H "Authorization: Bearer $TOKEN"
    ```
  </Tab>
</Tabs>

## Tool lifecycle

Tools move through states so you can rely on stable behavior:

<img src="https://mintcdn.com/hexelstudio-2127951d/utVkRjxsT1DGYlO5/assets/diagrams/tool-lifecycle.png?fit=max&auto=format&n=utVkRjxsT1DGYlO5&q=85&s=f04e50f3afb242fb8039aac6c08ef3ab" alt="Tool lifecycle states" width="1672" height="941" data-path="assets/diagrams/tool-lifecycle.png" />

| State        | Meaning                                  |
| ------------ | ---------------------------------------- |
| `draft`      | In development; not generally available. |
| `published`  | Available for use.                       |
| `deprecated` | Still works, but slated for removal.     |
| `retired`    | No longer callable.                      |

## Errors

| HTTP  | `code`            | When                                               |
| ----- | ----------------- | -------------------------------------------------- |
| `404` | —                 | The toolkit or tool slug doesn't exist.            |
| `400` | `INVALID_REQUEST` | Invalid `scope` on discover, or a malformed query. |

## Security

| Concern     | Detail                                                                                                                                 |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Scoping     | Discovery is scoped to your organization, workspace, and environment.                                                                  |
| Allow-lists | Tools excluded by a [workspace group](/docs/tool-gateway/workspace-groups) do not appear in discovery results.                              |
| Lifecycle   | Pin to `published` tools in production. `deprecated` tools continue to work but have a removal date — migrate before they are retired. |

## Common mistakes

* **Hardcoding tool slugs without discovery.** Use `discover_tools` to see what an agent can call in context.
* **Depending on deprecated tools.** Migrate before a tool reaches `retired`.

## Best practices

* Discover tools by scope rather than assuming availability.
* Pin to `published` tools for production workloads.
* Watch the [changelog](/docs/changelog) for deprecation notices.

## Related pages

<CardGroup cols={2}>
  <Card title="Connected Accounts" icon="link" href="/docs/tool-gateway/connected-accounts">
    Authorize a provider before using its tools.
  </Card>

  <Card title="Bindings" icon="link-horizontal" href="/docs/tool-gateway/bindings">
    Grant an agent access to a toolkit.
  </Card>

  <Card title="Executing Tools" icon="play" href="/docs/tool-gateway/execution">
    Call a tool once you have found it.
  </Card>

  <Card title="Tools (concept)" icon="plug" href="/docs/concepts/tools">
    The model behind the catalog.
  </Card>
</CardGroup>