# Curating tools

A hosted server exposes a curated selection of the tool definitions in the project's active deployment. Curating covers two tasks: choosing which tools the server exposes, and editing each tool's metadata so an LLM picks and uses it correctly. For guidance on scoping a server to a task, see [Choosing which tools a server exposes](/docs/ai-control-plane/mcp-gateway/concepts#choosing-which-tools-a-server-exposes).

Curation applies to hosted servers only. Remote and tunneled servers list their tools live and use [recorded tool metadata](/docs/ai-control-plane/mcp-gateway/remote-servers#recording-tool-metadata) instead. See [Tool discovery](/docs/ai-control-plane/mcp-gateway/tool-discovery).

## Access requirements

> Curating a server's tools and editing tool variations require the `mcp:write` scope. The default [Admin role](/docs/ai-control-plane/org-admin/roles-and-permissions) holds it and the Member role does not.

## Choose the tools a server exposes

Open the server from [**MCP Gateway > MCP**](https://ai.speakeasy.com/@self/projects/default/mcp) and select its **Tools** tab. Remove tools that agents do not need, or click **Add Tools** to add tools from any of the project's sources. The same tab lists the resources and prompts the server serves.

Tools can also be added or removed from the [Playground](/docs/ai-control-plane/mcp-gateway/building-servers/playground) through **Manage tools**.

## Edit a tool

Endpoints in an OpenAPI document often lack summaries and descriptions that convey their intent. When a tool definition inherits a vague or incomplete description, an LLM may struggle to decide when to call the tool, how to use it, or how to interpret its output. Improving tool metadata is a form of prompt engineering and a critical step in building reliable agents.

There are two ways to improve a tool's metadata:

- Edit the OpenAPI document and add the `x-gram` extension to the endpoint to override or enrich the tool's metadata. See [Optimize the document for LLMs](/docs/ai-control-plane/mcp-gateway/building-servers/openapi#optimize-the-document-for-llms).
- Edit the tool directly in the dashboard. An edit made this way is called a tool variation.

A tool variation overrides a tool's metadata without changing the underlying source. Beyond the name and description, a variation can override the tool's tags, its MCP annotations (the title and the read-only, destructive, idempotent, and open-world hints), and its confirmation prompt.

> Variations made in the dashboard are global. They apply to the tool everywhere it is used, across every MCP server.

Edit a tool from the **Tools** tab of a hosted server, or from the **Tools** tab of a source's detail page, which opens from the **Sources** tab of the **MCP** page (see [Sources](/docs/ai-control-plane/mcp-gateway/building-servers/sources)). Each tool has an actions menu behind its three-dot button.

### Rename a tool

Open the actions menu, select **Edit name**, and update the name in the dialog that opens.

  <source
    src="/assets/docs/ai-control-plane/videos/tool-variations/editing-tool-name.mp4"
    type="video/mp4"
  />

### Change a description

Open the actions menu and select **Edit description**. Validate and save the new description in the dialog:

  <source
    src="/assets/docs/ai-control-plane/videos/tool-variations/editing-tool-description.mp4"
    type="video/mp4"
  />

### Edit annotations and tags

The same menu holds **Edit annotations** and **Edit tags** for tools generated from OpenAPI documents and functions. Tags set here drive [tag-based tool filtering](/docs/ai-control-plane/mcp-gateway/building-servers/tool-filtering#override-tags-from-the-dashboard).

## Tool kinds and URNs

Every tool definition is identified by a URN in the format `tools:::`. The kind reflects how the tool executes:

- `http`: generated from an OpenAPI operation and executed as an HTTP request to the API
- `function`: backed by a function
- `externalmcp`: proxied to a third-party MCP server added from the catalog or registered by URL
- `tunneledmcp`: proxied to a private MCP server connected through a tunnel
- `prompt`: a prompt template exposed as a tool
- `platform`: a built-in platform tool

Tool URNs appear in the API and SDK when selecting the tools a server exposes. Renaming an operation ID changes the URN, so tool variations keyed to the old URN stop applying. See [How a change propagates](/docs/ai-control-plane/mcp-gateway/building-servers#how-a-change-propagates).

---

Index of every Speakeasy page for agents: [llms.txt](https://www.speakeasy.com/llms.txt). AI control plane and MCP gateway content in one file: [llms-full.txt](https://www.speakeasy.com/llms-full.txt). Any page is available as markdown by appending `.md` to its URL or by requesting it with `Accept: text/markdown`.