---
schema_version: "1"
id: 9f538f6eb0b0d93559aa41222f52e8eb12717364f6acdd2eb72c1a78f21fb36d
title: MCP Tools Progressive Disclosure Policy
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/gateway/latest/policies-included-mcp-progressive-disclosure.md
canonical_url: https://docs.mulesoft.com/gateway/latest/policies-included-mcp-progressive-disclosure
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 3c77a7bb21a416414f93f4c3b6d8c64c7813ff944934e46ce78c34711f65f7bc
description: MuleSoft Documentation Site
release: "1.14"
latest: true
---
---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy, mcp, progressive disclosure, tool search
---

# MCP Tools Progressive Disclosure Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>MCP Tools Progressive Disclosure</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Reduces context window token cost by exposing tools on-demand through search</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>MCP</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/mcp-progressive-disclosure-release-notes">MCP Tools Progressive Disclosure</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>No return codes exist for this policy.</p></td></tr></tbody></table>

> [!NOTE] This policy supports Model Context Protocol (MCP) version 2025-06-18 and earlier. To learn
> more about MCP, see [MCP Specification](https://modelcontextprotocol.io/specification/2025-06-18).

## Summary

The MCP Tools Progressive Disclosure policy reduces an MCP client’s context-window token cost by
hiding the `tools/list` catalog behind these tools:

- **`search_tools`**: Finds relevant tools on demand by matching a query against tool names and
  descriptions.

- **`invoke_tool`**: Calls a tool discovered via `search_tools`.

With this policy, you can:

- Reduce token consumption by exposing tools on-demand rather than listing all tools up front.

- Keep frequently-used tools immediately available through `hotTools` configuration.

- Support paginated search results for large tool catalogs.

- Preserve normal tool invocation semantics for upstream policies.

> [!IMPORTANT] This policy must be positioned after the
> [MCP Support Policy](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-support) but before any other MCP authorization
> policies, such as [access control](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-attribute-access-control),
> [tool mapping](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-tool-mapping), or
> [schema validation](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-schema-validation) policies. To learn more about MCP
> authorization policies, see
> [Configuring MCP Access Control Policies](https://docs.mulesoft.com/gateway/latest/policies-mcp-access-control-together).

The policy performs no tool caching. Every `tools/list`, `search_tools`, and `invoke_tool` request
is resolved against the live upstream, so the client always sees the real, per-caller-filtered
upstream state.

## Configuring Policy Parameters

### Omni Gateway Local Mode

The MCP Tools Progressive Disclosure policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td><div><div><p>Search Result Limit</p></div></div></td><td><div><div><p>The maximum number of matches a <code>search_tools</code> query returns per page when the query omits its own <code>limit</code> parameter.</p></div></div></td><td><div><div><p><code>20</code></p></div></div></td></tr><tr><td><div><div><p>Hot Tools</p></div></div></td><td><div><div><p>Tool names or patterns that bypass disclosure. Matched tools appear in the client-facing <code>tools/list</code> with their original upstream schemas.</p></div></div></td><td><div><div><p><code>[]</code> (empty)</p></div></div></td></tr><tr><td><div><div><p>Meta Tool Prefix</p></div></div></td><td><div><div><p>A prefix prepended to the <code>search_tools</code> and <code>invoke_tool</code> meta-tool names to avoid namespace collisions with upstream tool names. The prefix is concatenated directly with no separator added (such as <code>_</code>) in the prefix value itself.</p></div></div></td><td><div><div><p><code>""</code> (empty)</p></div></div></td></tr></tbody></table>

### Configuration Example

```yaml
- policyRef:
    name: mcp-tools-progressive-disclosure-policy-flex
  config:
    searchResultLimit: 20
    hotTools:
      - "get_weather"
      - "list_*"
    metaToolPrefix: "mcp_"
```

> [!NOTE] The `metaToolPrefix` value `"mcp_"` produces `mcp_search_tools` and `mcp_invoke_tool`. The
> underscore is part of the configured prefix, not added automatically.

## How It Works

### Meta-Tool Advertisement

When a client requests `tools/list`, the policy:

1.  Forwards the request upstream to get the live, per-caller-filtered tool catalog.

2.  Replaces the full catalog with the two meta-tools (`search_tools` and `invoke_tool`).

3.  Includes any tools matching the configured `hotTools` patterns with their original schemas.

### Tool Discovery

When a client calls `search_tools`:

1.  The policy forwards a synthesized `tools/list` request upstream.

2.  The upstream [access control policy](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-attribute-access-control) filters the
    list per caller.

3.  The policy runs the search query against the filtered list.

4.  Matching tools are returned with their full schemas, sufficient to construct an `invoke_tool`
    call.

### Tool Invocation

When a client calls `invoke_tool`:

1.  The policy rewrites the request as a native `tools/call` with the wrapped tool name.

2.  All upstream policies see the real tool name (not `invoke_tool`).

3.  The response is returned to the caller unchanged.

This normalization ensures that access control, tool mapping, and other policies operate on the real
tool name without progressive-disclosure awareness.

## Hot Tools Configuration

The `hotTools` configuration enables you to keep frequently-used tools immediately visible without
requiring a search. Tools matching the patterns appear in `tools/list` alongside `search_tools` and
`invoke_tool`.

### Pattern Matching

- Use exact names: `"get_weather"`.

- Use glob patterns: `"list_*"`, `"*_info"`.

- Matches are evaluated against the live upstream `tools/list` response on every request.

- Only tools the caller is authorized to see (per the chain’s
  [access control policy](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-attribute-access-control)) will match.

### Use Cases

**Frequently-used tools**: Keep high-traffic tools immediately available to reduce search
round-trips.

```yaml
hotTools:
  - "get_weather"
  - "get_user"
```

**Namespace patterns**: Expose all tools from a specific namespace.

```yaml
hotTools:
  - "weather_*"
  - "user_*"
```

## Search Tool Usage

The `search_tools` meta-tool accepts a JSON object with the following parameters:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>query</code></p></div></div></td><td><div><div><p>string</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>A case-insensitive regular expression to match against tool names and descriptions. Separate alternative keywords with <code>|</code> (spaces match literally).</p></div></div></td></tr><tr><td><div><div><p><code>limit</code></p></div></div></td><td><div><div><p>integer</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Maximum number of results to return per page. If omitted, uses the configured <code>searchResultLimit</code>.</p></div></div></td></tr><tr><td><div><div><p><code>cursor</code></p></div></div></td><td><div><div><p>string</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Opaque pagination cursor from a prior search’s <code>nextCursor</code> field. Pass it back to fetch the next page.</p></div></div></td></tr></tbody></table>

### Example Request

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_tools",
    "arguments": {
      "query": "weather",
      "limit": 3
    }
  }
}
```

### Example Response

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Found 1 matching tool(s)."
      }
    ],
    "structuredContent": {
      "matches": [
        {
          "name": "get_weather",
          "description": "Return the current weather for a city",
          "inputSchema": {
            "type": "object",
            "required": ["city"],
            "properties": {
              "city": {
                "type": "string"
              }
            }
          }
        }
      ]
    }
  }
}
```

### Pagination

When more tools match than fit on a page, the response includes a `nextCursor` field under
`structuredContent`:

```json
{
  "structuredContent": {
    "matches": [...],
    "nextCursor": "eyJxIjoid2VhdGhlciIsIm8iOjIwfQ=="
  }
}
```

To fetch the next page, pass the cursor back in the `arguments`:

```json
{
  "method": "tools/call",
  "params": {
    "name": "search_tools",
    "arguments": {
      "cursor": "eyJxIjoid2VhdGhlciIsIm8iOjIwfQ=="
    }
  }
}
```

Each page resolves against a fresh upstream `tools/list`, ensuring the correct authorization. The
`query` parameter may be omitted when using a cursor (the cursor carries it).

## Invoke Tool Usage

The `invoke_tool` meta-tool wraps a call to a discovered tool. It accepts:

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>name</code></p></div></div></td><td><div><div><p>string</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>The tool name returned from <code>search_tools</code></p></div></div></td></tr><tr><td><div><div><p><code>arguments</code></p></div></div></td><td><div><div><p>object</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>The tool’s input parameters as returned in the <code>inputSchema</code> from <code>search_tools</code></p></div></div></td></tr></tbody></table>

### Example Request

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "invoke_tool",
    "arguments": {
      "name": "get_weather",
      "arguments": {
        "city": "San Francisco"
      }
    }
  }
}
```

The policy rewrites this as a native `tools/call`:

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "city": "San Francisco"
    }
  }
}
```

All upstream policies see `get_weather` (not `invoke_tool`), ensuring access control, tool mapping,
and other policies operate correctly.

## Filter Chain Ordering

The MCP Tools Progressive Disclosure policy must be positioned after the
[MCP Support Policy](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-support) but before any other MCP policies in the filter
chain, particularly before any policy that reads tool names (access control, tool mapping, schema
validation).

If positioned after an access control policy, that policy would see `invoke_tool` (the meta-tool) in
the request and gate the envelope—not the real tool inside—creating an authorization bypass.

## Delegated Authorization

The policy maintains per-caller authorization parity by delegating to the chain:

1.  A `search_tools` call triggers a synthesized `tools/list` request upstream.

2.  The upstream [access control policy](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-attribute-access-control) filters the
    list per caller.

3.  The policy runs the query against the filtered list.

4.  Only tools the caller is authorized to see are included in results.

This ensures:

- Callers don’t see tools they cannot invoke.

- Results reflect live authorization state.

- No caching of authorization decisions.

If no [access control policy](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-attribute-access-control) is present,
`search_tools` returns the full unfiltered catalog—the same as a direct `tools/list` would in that
chain.

## Error Responses

The policy returns JSON-RPC error objects with a stable `data.reason` field for machine-checkable
error handling.

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Case</th><th>Code</th><th><code>data.reason</code></th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Malformed <code>invoke_tool</code></p></div></div></td><td><div><div><p><code>-32602</code></p></div></div></td><td><div><div><p><code>invalid_params</code></p></div></div></td><td><div><div><p>Missing or invalid <code>arguments.name</code> or <code>arguments.arguments</code></p></div></div></td></tr><tr><td><div><div><p>Malformed <code>search_tools</code></p></div></div></td><td><div><div><p><code>-32602</code></p></div></div></td><td><div><div><p><code>invalid_params</code></p></div></div></td><td><div><div><p>Empty/missing/non-string query, exceeds 256 characters, invalid regex, bad <code>limit</code>, missing <code>id</code>, malformed <code>cursor</code>, or <code>cursor</code>/<code>query</code> mismatch</p></div></div></td></tr></tbody></table>

Errors produced upstream (access control denials, upstream tool errors) pass through unchanged.

## See Also

- [MCP Access Control: How the Policies Work Together](https://docs.mulesoft.com/gateway/latest/policies-mcp-access-control-together)

- [MCP Tool Mapping](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-tool-mapping)

- [MCP Global Access](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-global-access)

- [MCP Attribute-Based Access Control](https://docs.mulesoft.com/gateway/latest/policies-included-mcp-attribute-access-control)

- [Included Policies Directory](https://docs.mulesoft.com/gateway/latest/policies-included-directory)