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

# Tool Modes

> Control how StackOne MCP registers tools — individual actions or search-and-execute for reduced context footprint.

## Overview

The StackOne MCP endpoint supports two tool registration modes controlled by the `tool-mode` query parameter:

| Mode                   | Tools registered          | Best for                                                |
| ---------------------- | ------------------------- | ------------------------------------------------------- |
| `individual` (default) | One tool per action       | Agents with a small action set, or full tool visibility |
| `search_execute`       | 2 tools: search + execute | Large catalogs, context window constraints              |

***

## Individual Mode (Default)

When `tool-mode` is omitted or set to `individual`, StackOne registers each enabled action as its own MCP tool (e.g., `bamboohr_list_employees`, `ashby_list_jobs`).

This is the right choice when:

* Your integration config has a small, focused action set
* You want the LLM to see every available tool upfront
* Your MCP client supports large tool lists without performance degradation

***

## Search & Execute Mode

```
https://api.stackone.com/mcp?tool-mode=search_execute&x-account-id=<ACCOUNT_ID>
```

Instead of registering one tool per action, `search_execute` mode exposes exactly **two tools**:

| Tool                        | Description                                                                                                                  |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `{provider}_search_actions` | Takes a natural language query and returns ranked matching actions with their `action_id`, description, and similarity score |
| `{provider}_execute_action` | Executes any action by its `action_id`                                                                                       |

For example, for a BambooHR account the tools would be `bamboohr_search_actions` and `bamboohr_execute_action`.

### Why use this mode?

A typical integration exposes hundreds of actions. Sending every tool definition to the LLM on every request:

* Consumes significant context window tokens
* Can slow down tool listing in the client
* May exceed context limits for models with smaller windows

Search & execute mode keeps the token footprint constant (two tools) regardless of how many actions the integration supports. The agent first calls `search_actions` with a natural language description of what it wants to do, then calls `execute_action` with the returned `action_id`.

### How the agent flow works

```
1. Agent calls {provider}_search_actions(query="list all employees with their departments")
   → Returns: [{ action_id: "list_employees", description: "...", score: 0.94 }, ...]

2. Agent calls {provider}_execute_action(action_id="list_employees", query={ include: "department" })
   → Returns: employee records from the provider
```

The search tool accepts:

* `query` (required) — natural language description of the task
* `top_k` (optional, default 10, max 50) — number of results to return

The execute tool accepts:

* `action_id` (required) — the `action_id` returned by the search tool
* `path` (optional) — path parameters (e.g. `{ "id": "emp_123" }` for a get-by-id action)
* `query` (optional) — query parameters (filters, pagination, etc.)
* `body` (optional) — request body for create/update actions
* `headers` (optional) — additional HTTP headers

<Warning>
  The agent **must** call `search_actions` first to discover valid `action_id` values before calling `execute_action`. Do not assume or hardcode action IDs — they are discovered at runtime based on what is enabled for your account.
</Warning>

### Example: Enable in Claude Desktop

Add `?tool-mode=search_execute` to the MCP URL in your client config:

```json theme={null}
{
  "mcpServers": {
    "stackone-bamboohr": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://api.stackone.com/mcp?tool-mode=search_execute",
        "--header",
        "Authorization: Basic <BASE64_APIKEY_COLON>",
        "--header",
        "x-account-id: <ACCOUNT_ID>"
      ]
    }
  }
}
```

### Example: Enable in Claude Code

```bash theme={null}
BASE64_KEY=$(echo -n 'YOUR_STACKONE_API_KEY:' | base64 | tr -d '\n')

claude mcp add stackone-bamboohr -- npx -y mcp-remote@latest \
  "https://api.stackone.com/mcp?tool-mode=search_execute" \
  --header "Authorization: Basic $BASE64_KEY" \
  --header "x-account-id: YOUR_ACCOUNT_ID"
```

### Example: Enable via direct HTTP

```bash theme={null}
curl -X POST "https://api.stackone.com/mcp?tool-mode=search_execute" \
  -H "Authorization: Basic <BASE64_APIKEY_COLON>" \
  -H "x-account-id: <ACCOUNT_ID>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":"tools-1","method":"tools/list"}'
```

***

## Combining with Param Style

`tool-mode` can be combined with the `param-style` query parameter to control how tool input schemas are structured:

| `param-style` value | Schema structure                                                    |
| ------------------- | ------------------------------------------------------------------- |
| `nested` (default)  | Parameters grouped into `path`, `query`, `body`, `headers` objects  |
| `flat_smart`        | All parameters at the top level; conflicts resolved automatically   |
| `flat_root`         | All parameters at the top level; any conflicting names are prefixed |

```
https://api.stackone.com/mcp?tool-mode=search_execute&param-style=flat_smart
```

Both parameters are independent — you can use either, both, or neither.

***

## Choosing the Right Mode

| Scenario                                                           | Recommended mode                          |
| ------------------------------------------------------------------ | ----------------------------------------- |
| Small action set (\< 50 tools)                                     | `individual`                              |
| Large integration with many actions                                | `search_execute`                          |
| Model with limited context window                                  | `search_execute`                          |
| Agent needs to see all tools explicitly                            | `individual`                              |
| Multi-account management via the [Management MCP](/mcp/quickstart) | `individual` (management tools are fixed) |

<Tip>
  Search & execute mode uses semantic search over your enabled actions. For best results, write queries that describe the business task rather than the technical operation — e.g., "find employees hired this year" rather than "list employees filtered by start date".
</Tip>