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

# Advanced Tool Search

> Reduce token and agent context overload. Discover the right action by natural language, then run it.

<Note>
  StackOne [actions](/gateway/concepts/actions) are exposed to agents as **tools**. An action in the catalog becomes a tool in your agent's hands. The two terms describe the same operation from either side.
</Note>

There is a real problem when an agent is exposed to hundreds of tools. Loading them all into the model's context:

* **Burns tokens**: every tool definition consumes context before the agent does any work
* **Hurts accuracy**: LLMs make worse tool selections as the candidate set grows; more tools without structure become noise
* **Hits provider caps**: OpenAI caps function definitions at \~128 per request

To help solve this issue, StackOne offers **Advanced Tool Search**. This replaces a long list of tools with two:

1. **Search** - finds actions by natural language
2. **Execute** - runs the action returned by **Search**.

## Key features

<CardGroup cols={2}>
  <Card title="Scales to thousands of tools" icon="chart-line">
    Search returns only the relevant actions for each query, however large the catalog.
  </Card>

  <Card title="Improves accuracy" icon="bullseye">
    Only relevant tools exposed per request, reducing misfires and hallucinations.
  </Card>

  <Card title="Account-aware" icon="shield-check">
    Filters results to tools available for configured account IDs, respecting authentication boundaries.
  </Card>

  <Card title="Framework-ready" icon="puzzle-piece">
    Returns a Tools collection with converters for OpenAI, LangChain, Vercel AI SDK, and more.
  </Card>
</CardGroup>

## What it saves

Loading every tool definition scales with your catalog. Hundreds of actions can run to hundreds of thousands of tokens before the agent does any work. Advanced Tool Search keeps that footprint flat: two tools, whatever the catalog size.

<div style={{ margin: "1.5rem 0", display: "flex", flexDirection: "column", gap: "1.25rem" }}>
  <div>
    <div style={{ fontSize: "0.875rem", fontWeight: 600, marginBottom: "0.4rem" }}>Individual tools: 500 tools loaded · \~150,000 tokens</div>

    <div style={{ height: "1.25rem", width: "100%", background: "#f87171", borderRadius: "6px" }} />
  </div>

  <div>
    <div style={{ fontSize: "0.875rem", fontWeight: 600, marginBottom: "0.4rem" }}>Advanced Tool Search: 2 tools · \~900 tokens</div>

    <div style={{ height: "1.25rem", width: "0.6%", minWidth: "10px", background: "#34d399", borderRadius: "6px" }} />
  </div>
</div>

<Note>
  Illustrative, exact counts depend on the actions enabled and the model.
</Note>

## Example flows

| Linked connector | User prompt                              | Search tool finds                                                                | Execute tool runs                            |
| ---------------- | ---------------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------- |
| *Any*            | A description of the task                | Ranked actions with IDs and descriptions: only from the connectors you've linked | The chosen `action_id` with its params       |
| HiBob            | "Request time off for Alice next Friday" | `hibob_create_time_off_request`                                                  | Creates the time-off request in HiBob        |
| Jira             | "Look up ticket ABC-123"                 | `jira_get_issue`                                                                 | Returns the issue details from Jira          |
| Google Drive     | "Find training docs on GDPR"             | `googledrive_list_files`                                                         | Searches the linked drive for matching files |

## Setting it for a whole project

**Project Settings → MCP Settings → Advanced Tool Search** decides this for every new connection in a project, rather than leaving it to whoever authorizes:

| Setting                                  | Effect                                                                                                                                     |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Allowed**                              | On by default. Turn it off and connections can only use individual tools, and Advanced Tool Search is refused even if a client requests it |
| **Mode: Let the connecting user choose** | The default. The consent screen shows a **Load tools when needed** toggle, on unless the user turns it off                                 |
| **Mode: Enforced for all connections**   | Always used, and the consent screen shows the decision instead of a toggle                                                                 |

The setting applies to new connections, so it does not change grants that already exist. Where a mode is not enforced here, each user chooses it on the consent screen while authorizing, with a toggle labelled **Load tools when needed**. See [Agent Setup](/connect/agent-setup/overview#what-the-user-sees) for where it appears.

## When to use it

Use Advanced Tool Search when your agent spans many SaaS systems — dozens to thousands of tools — or targets models with limited context windows. For a small, focused action set where you want the model to see every tool, use individual tools instead.

<CardGroup cols={2}>
  <Card title="Agent Setup" icon="robot" href="/connect/agent-setup/overview">
    Turn it on in your agent's client, with ready-to-paste configs for ChatGPT, Claude, Cursor, and more.
  </Card>

  <Card title="Tool Discovery" icon="magnifying-glass" href="/features/tool-discovery">
    Embedding StackOne into your own code? Implement Advanced Tool Search and the other discovery methods.
  </Card>
</CardGroup>