Progressive Disclosure

Progressive disclosure is an opt-in setting on a remote-agent grant. Instead of listing every tool the grant may use, tools/list on /mcp returns three small tools the agent uses to search, describe and call tools on demand. It saves context. It is not a security boundary.

Why use it?

With many subscribed MCPs, tools/list can be thousands of tokens of descriptions and schemas before the agent does anything, and long lists make tool selection worse. Remote agents often can't filter lists client-side. In Progressive mode the agent starts with three definitions and fetches only the tools it needs, at the cost of one or two extra round trips per new tool.

Choosing the mode

Each grant has a Tool list setting: Full (the default, today's behavior) or Progressive.

• You choose it when you approve an OAuth consent request, or when you create a one-shot grant in Agent Access. Only the signed-in user chooses it. It is never an authorize parameter, so an agent can't ask for it.
• It is stored on the grant and shown in the grants list. Existing grants stay Full. New grants default to Full unless the user picks Progressive.
• Denying a consent request sends no mode.

The three tools

In Progressive mode tools/list returns exactly these, with fixed definitions written by the server:

• Limits. query is at most 200 characters. limit defaults to 20 and is capped at 50. Matching is a case-insensitive text match over tool name and description; there are no embeddings in v1. The response size is capped. Summaries are stripped of control, zero-width and bidirectional characters; a tool whose name contains them is left out of search results.
• Descriptions are cut to 500 code points, the same as tools/list in Full mode. Schemas are served in full.
• call_tool.arguments is a free-form object in the advertised schema. The server validates it against the tool's approved inputSchema and returns a precise error on mismatch.
• Ambiguous names. If two MCPs expose the same tool name, describe_tool and call_tool return ambiguous: specify mcp with the candidate MCP names instead of picking one. Search results carry mcp, so the agent can pass it back.
• Unknown means unknown. Search and describe treat tools that are out of scope, pending review, rejected or revoked exactly like tools that don't exist. Pending, rejected and revoked tools are also "unknown" when called. A call to a tool you're subscribed to but that is outside the grant's scopes returns 403 insufficient_scope, as in Full mode, so the existence of such a tool is not hidden from the agent.

Same permissions in both modes

Progressive disclosure changes only what tools/list shows. Every request still goes through the same checks as in Full mode: token scope, the bound client's subscriptions, profile authorization, the tool allowlist, kill switches, tool pinning, argument validation and rate limits.

• A call outside the grant's scopes still returns 403 insufficient_scope, including when wrapped in ambassador__call_tool.
• A tool can still be called by name. A client that learned a name from search, or cached an earlier list, may call it directly; authorization is per call. Progressive mode doesn't hide tools, it just doesn't list them. Don't use it to keep a tool away from an agent: use scopes, the allowlist or unsubscribe for that.
• The meta-tools also work on Full-mode grants. This widens nothing, because the same checks apply.
• Describe and search return the approved definition, never the live one, and a tool pending review is invisible to search, describe and call.

Reserved names and nesting

• The ambassador__ prefix is reserved. A downstream tool whose name starts with it is hidden and flagged at discovery and pinning; the rest of that MCP keeps working.
• The three meta-tool names always go to the meta-tools.
• Nesting isn't allowed. If describe_tool or call_tool is given a meta-tool name, or a name that is empty, not a string or longer than 256 characters, the result is "unknown tool" and nothing runs. The scope check unwraps call_tool exactly one level, including inside batches.

Audit and rate limits

• Tool calls are audited as the underlying tool, with via: ambassador__call_tool and the grant's disclosure_mode.
• Search and describe are audited as agent_tool_discovery with the query length and a hash prefix and the result count. The raw query and the result bodies aren't audited.
• Search and describe have their own per-grant rate bucket, at twice the call limit. call_tool uses the normal call limit.

Behavior to know

• No list_changed. /mcp is stateless, so no notifications/tools/list_changed is sent in either mode. After an admin approves a pin, the agent sees it on its next search or call.
• Not for the stdio client. The Ambassador Client uses its own protocol and isn't affected.
• No per-client cap in v1. The mode is a per-grant user choice; an admin can't force it per OAuth client.
• Text matching only. If search proves too weak for a large catalog, ranking can improve behind the same tool contract.