Tool Search plugin
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_toolranks the real tools by meaning against a query.get_toolreturns one tool’s input schema.execute_toolcalls a real tool by name.
The gateway ranks tools with embeddings from an OpenAI-compatible embedding service that you configure.
Where it runs
Set up the plugin
Add a Tool Search instance to an MCP route in the console.
Prerequisites
- An MCP route that serves the tools to search.
- On a data plane that you manage, an embedding service that implements the OpenAI
/embeddingsAPI. You need its base URL, the model name, and the model’s vector dimension. If the service needs a key, store the key in a vault that the data plane can read. For more information, see Manage credentials and vaults. - On a Postman-hosted data plane, nothing else. The console uses the managed embedder.
Steps
- In the console sidebar, select Plugins, then open the All tab.
- Find tool-search and select Use.
- In Instance name, enter a name, for example
tool-search-production. - In Routes, select the MCP route. If you select several routes, the console creates one instance for each and Instance name becomes Base name.
- Under Configuration and Embedder, the Type is Managed on a Postman-hosted data plane, and you don’t enter anything else. On a data plane that you manage, the Type is Custom. Set the following values:
- URL: The embedding service’s base URL, for example
https://embeddings.example.com/v1. Don’t end it with/or/embeddings. - Model: The model name, for example
text-embedding-3-small. - Vector dimension: The size of the model’s vectors, for example
1536. - (Optional) API key secret: A secret reference that your data plane can read, such as an AWS Secrets Manager ARN.
env://,file://, andvault://references aren’t supported.
- URL: The embedding service’s base URL, for example
- (Optional) Expand Search results to set Default results, Maximum results, and Maximum description length. The defaults are
10,25, and120characters. - Make sure Enabled is selected, then select Create instance.
Verify it works
Connect an MCP client to the route, as in Connect an MCP client, and list the tools. The list contains only search_tool, get_tool, and execute_tool. Then call search_tool with a query, such as create an issue. The result lists the best-matching real tools, each with a name, a summary, and a score.
Fix common problems
search_toolreturns an error result that says the embedder is unavailable. The gateway can’t get vectors from the embedding service. Check URL, Model, and API key secret, and check that Vector dimension matches the model. A vector of any other length counts as a failure.tools/liststill shows the real tools. The route has no enabled Tool Search instance. Check the route and the Enabled setting.- A tool search error says tool search isn’t initialized. The data plane couldn’t build the search from the first Tool Search configuration that it received. Correct that configuration, and then restart the data plane. Changes to the embedder settings take effect only after a restart.
- The console says to remove a trailing slash or
/embeddings. The gateway appends/embeddingsto URL. Remove that part from the URL. - The console says default results can’t exceed the maximum. Set Default results to a value at or below Maximum results, which is
25unless you change it.
Configuration
Results returned when the client doesn’t give a usable limit. At least 1, and not above result_limit_max.
The maximum number of results.
The maximum characters in each tool summary.
The embedding service.
The service’s base URL. The gateway calls POST <base_url>/embeddings with input and model, in the OpenAI format, so the URL can’t end with / or /embeddings. The console requires it.
The embedding model. The console requires it.
The vector length the model returns, at least 1. Vectors of any other length count as a failure.
A secret reference that the data plane can read, such as an AWS Secrets Manager ARN, for the service’s API key. The gateway sends the key as Authorization: Bearer. The console refuses env://, file://, and vault:// references.
The time limit for each call to the embedding service.
The total time to embed tools that don’t have a vector yet.
Optional. With quantize and cache_scope, it only labels the vector index.
Tools per embedding call. The console starts a new instance at 32, because Fabric’s own embedder accepts at most 32 inputs per request.
Example
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.
The embedder.api_key_ref setting accepts a name from global.secrets.refs or an entry in a remote secret store, such as an AWS Secrets Manager ARN. It doesn’t accept env:// or file:// references.

