> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.fabricgateway.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.fabricgateway.ai/_mcp/server.

# Tool Search plugin

> Reference for the Tool Search plugin, which replaces a large MCP tool list with three tools that search, describe, and call the real tools.

The Tool Search plugin keeps a large tool catalog out of the client's context. On a route with Tool Search, `tools/list` returns three gateway tools instead of the route's real tools:

* `search_tool` ranks the real tools by meaning against a query.
* `get_tool` returns one tool's input schema.
* `execute_tool` calls a real tool by name.

The gateway ranks tools with embeddings from an OpenAI-compatible embedding service that you configure.

## Where it runs

|             |                                          |
| ----------- | ---------------------------------------- |
| Protocols   | MCP routes                               |
| Scope kinds | `route` only                             |
| Phase       | Request. The MCP handling does the work. |

## Configuration

**`result_limit_default`** `integer` — default: 10

Results returned when the client doesn't give a usable `limit`. At least 1, and not above `result_limit_max`.

---

**`result_limit_max`** `integer` — default: 25

The maximum number of results.

---

**`summary_max_len`** `integer` — default: 120

The maximum characters in each tool summary.

---

**`embedder`** `object` — required

The embedding service.

---

**`embedder.base_url`** `string`

The service's base URL. The gateway calls `POST <base_url>/embeddings` with `input` and `model`, in the OpenAI format.

---

**`embedder.model`** `string`

The embedding model.

---

**`embedder.dimension`** `integer` — required

The vector length the model returns, at least 1. Vectors of any other length count as a failure.

---

**`embedder.api_key_ref`** `string`

A named secret reference for the service's API key, sent as `Authorization: Bearer`. Raw `env://` and `file://` references are refused.

---

**`embedder.timeout`** `duration` — default: 5s

The time limit for each call to the embedding service.

---

**`embedder.cold_start_timeout`** `duration` — default: 60s

The total time to embed tools that don't have a vector yet.

---

**`embedder.provider`** `string`

Optional. With `quantize` and `cache_scope`, it only labels the vector index.

---

**`embedder.max_batch`** `integer` — default: 256

Tools per embedding call.

---

## Example

```json
{
  "name": "tool-search",
  "plugin_id": "tool-search",
  "scope": { "kind": "route", "name": "workspace-mcp" },
  "config": {
    "result_limit_default": 5,
    "embedder": {
      "base_url": "https://embeddings.example.com/v1",
      "model": "text-embedding-3-small",
      "dimension": 1536,
      "api_key_ref": "embedder-api-key"
    }
  }
}
```

On an Enterprise data plane, the Helm chart also deploys an embedding service, `fabric-gateway-embedder`, that serves the `BAAI/bge-small-en-v1.5` model with 384 dimensions. For the `embedder` settings that use it, see [Run the tool-search embedder](/run/embedder).

## Related guides

* [Connect an MCP server](/configure/connections/mcp-servers)
* [Connect an MCP client](/use/mcp/connect-a-client)