Skip to main content

Built-in Discovery Tools

When you enable the MCP Gateway on a ToolSet, the deployed MCP Server automatically exposes five built-in discovery tools that AI agents can use to find, inspect, and invoke any tool in the Gateway catalog at runtime. These tools sit alongside your ToolSet's regular tools and require no additional configuration on the client side -- any MCP-compatible agent that connects to the server discovers them through tools/list like any other tool.

Why Discovery Tools?​

A Gateway-enabled ToolSet can aggregate tools from multiple external MCP servers and many Nexla connectors. Listing every one of these tools to an AI agent on each request would quickly overwhelm the agent's context window, slow down tool selection, and make even simple prompts harder for the model to reason about.

The discovery tools solve this by giving the agent a small, fixed surface for tool discovery. Instead of seeing the entire catalog up front, the agent searches the catalog when it needs to, inspects the specific tool it intends to call, and then invokes it -- all without leaving the MCP session.

When They Appear​

The discovery tools are exposed automatically by any MCP Server backed by a Gateway-enabled ToolSet. If you have not enabled the Gateway on a ToolSet, only the ToolSet's regular tools are listed.

note

The discovery tools never replace your ToolSet's regular tools. Both appear together in tools/list, and agents can call either kind in the same session.

The Five Discovery Tools​

ToolWhat It Does
search_toolsFinds tools in the Gateway catalog by keyword or natural-language description.
describe_toolReturns the full schema and usage hints for a specific tool the agent plans to call.
call_toolExecutes a Gateway tool with the parameters the agent provides.
list_nexla_vendors_with_available_credentialsLists the Nexla vendor credentials available to the caller, so the agent can scope its search to vendors it can already authenticate against.
create_nexla_credentialReturns an auto-generated link that lets the user securely create and save a new credential on Nexla when a tool requires one the caller does not yet have.

For the full input and output schemas, see the Gateway Meta-Tools API reference.

How an Agent Uses Them​

A typical agent interaction follows a discover-then-execute pattern:

  1. Check available credentials -- The agent calls list_nexla_vendors_with_available_credentials to learn which vendors it can use. This step is optional but reduces the chance of hitting a credential prompt mid-execution.
  2. Search the catalog -- The agent calls search_tools with a natural-language description of what it needs (for example, "list customers from our Shopify store"). The Gateway returns the most relevant matches, ranked by semantic similarity when available.
  3. Inspect the chosen tool -- The agent calls describe_tool with the exact tool name from the search results to see the input schema and any vendor or server context.
  4. Execute the tool -- The agent calls call_tool with the tool name and the parameters it derived from the schema. The Gateway resolves the appropriate credential or connects to the registered external MCP server, runs the tool, and returns the result.

If at any point the agent needs a credential that does not exist, it can call create_nexla_credential to receive a secure link that the end user can follow to create one on Nexla.

Working with Credentials Through Discovery​

Some Gateway tools are backed by Nexla connectors and need a credential to run. The discovery tools surface this requirement to the agent so it never has to handle secrets directly:

  • describe_tool flags vendor-backed tools by including a credential_info block that names the vendor whose credential the Gateway will resolve at runtime.
  • call_tool returns a credential_required response if the caller has no usable credential, along with a link to create one. The tool result itself contains no secrets.
  • create_nexla_credential returns an auto-generated link to the Nexla credential-creation flow for a specific vendor. The credential is created securely on Nexla -- the link is the only artifact the agent ever sees. Once the user finishes creating the credential, the agent can retry the original call_tool invocation and the Gateway will use the new credential automatically.
tip

Credentials are never returned to the agent or surfaced through any MCP response. The agent only ever sees a link to the Nexla credential UI -- secrets remain inside Nexla's secure vault at all times.

Tools from External MCP Servers​

For tools synced from a registered external MCP server, describe_tool includes a server_info block identifying the source server. When the agent invokes the tool through call_tool, the Gateway opens a short-lived session to that external server, runs the tool, and returns the result. The agent itself does not need to know about the external server -- it sees the tool as a uniform Gateway tool.

For details on registering external MCP servers and managing what gets synced, see Register External MCP Servers.

Name Collisions​

If you create a ToolSet tool whose name matches one of the discovery tools (for example, a tool literally named search_tools), your tool takes precedence and the matching discovery tool is omitted from tools/list for that ToolSet. To keep the discovery experience intact, avoid using these names for your own tools:

  • search_tools
  • describe_tool
  • call_tool
  • list_nexla_vendors_with_available_credentials
  • create_nexla_credential

Next Steps​