---
title: "Tools mode"
url: "/docs/mcp-gateway/tools-mode/"
kind: "concept"
summary: "Conventional MCP serving: agents list and call tools one at a time, discover a large catalog through tool_search, and call anything they may use by name."
---

> Arion site index: [/llms.txt](/llms.txt)

# Tools mode

Conventional MCP serving: agents list and call tools one at a time, discover a large catalog through tool_search, and call anything they may use by name.

Tools mode (`tools_mode: {}`) is the conventional way the MCP gateway serves its registry: every tool is an MCP tool, and an agent calls one per model turn with `tools/call`. Use it for simple tasks, and for clients that expect a classic tool list. The alternative for multi-step work is [code mode](@/docs/mcp-gateway/code-mode.md), which serves the same registry as a single `execute` tool.

## How an agent discovers tools

Discovery in tools mode is a short, stateless conversation:

1. **`initialize`** opens the session, as with any MCP server.
2. **`tools/list`** returns the caller's *eager* tools — the handful most tasks need. When the caller also has *progressive* tools (the default [disclosure mode](@/docs/mcp-gateway/tool-search.md), which keeps the long tail out of the list), the list includes one more tool: `tool_search`.
3. **`tool_search`** takes a query and returns the best-matching progressive tools as full MCP definitions — `name`, `description`, `inputSchema` and `outputSchema` — ranked with BM25 or an embeddings model. The description of `tool_search` itself names up to 256 progressive tools the caller may use, so a model can often pick a name without searching at all.
4. **`tools/call`** invokes any permitted tool by its qualified name, listed or not.

Listing is stateless: a search does not change later `tools/list` results, and there is no list-changed notification to handle. Non-MCP clients can search the same index over plain HTTP with [`POST /mcp/search`](@/docs/mcp-gateway/tool-search.md#search-over-http).

## What a call does

A `tools/call` is dispatched to the tool's backend — a templated HTTP request against a [REST backend's](@/docs/mcp-gateway/tools-and-rest-backends.md) cluster, or a forwarded call to an upstream MCP server — with the arguments validated against the input schema on the way in and, when an `output_schema` is declared, the response validated on the way out. [Per-tool authorization](@/docs/mcp-gateway/tool-authorization.md) decides from JWT claims which tools a caller can see, search and call.

## Filling the registry

The registry the mode serves is configured the same way in both modes: [static tools over REST backends](@/docs/mcp-gateway/tools-and-rest-backends.md), [OpenAPI documents](@/docs/mcp-gateway/openapi-tools.md), [federated MCP servers](@/docs/mcp-gateway/federation.md), and [tool discovery over xDS](@/docs/mcp-gateway/tool-discovery-tds.md).

## Next

- [Tool search](@/docs/mcp-gateway/tool-search.md) — configuring disclosure modes and ranking.
- [Build an MCP gateway](@/guides/mcp/mcp-gateway.md) — a complete tools-mode configuration with JWT and per-tool RBAC.
- [Code mode](@/docs/mcp-gateway/code-mode.md) — the same registry as one `execute` tool.