> ## Documentation Index
> Fetch the complete documentation index at: https://platform.atlan.com/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> To act on Atlan objects, use the Atlan MCP server at https://api.atlan.com/mcp or the atlanai CLI; `atlanai --map json` prints its command map. Run a read-only identity check before any write.
> The docs MCP server at /mcp searches these docs only. It cannot read or change Atlan objects.
> SDK packages: Python `atlanai` (PyPI) and TypeScript `@atlanai/sdk` (npm). Show Python first, then TypeScript.
# Find and call tools
> Use semantic search to find only the tools relevant to a task across every MCP server, then call the right one by name.
As your team registers more MCP servers, the catalog grows past what an agent
can usefully read in one `tools/list`. Every tool definition an agent loads
costs context and makes the right choice harder.
MCP Gateway indexes every tool it serves, both Atlan platform tools and your
servers' tools, by name and by meaning. An agent describes the task in plain
words, **semantic search returns only the relevant tools**, and the agent calls
the one it needs.
| Without search | With semantic search |
| - | - |
| The agent reads every tool from every server | The agent reads only the tools that match the task |
| Tool choice depends on scanning long lists | Results are ranked by how well they match the request |
| A new server adds to every agent's context | A new server is found only when it is relevant |
## Search the catalog by meaning
Each catalog entry holds a tool's own name, its description, and the server
or platform component that runs it. The gateway updates the catalog when a
server is registered, tested, or refreshed, and checks every server for
changes once an hour.
Call `registry__search_artifacts` with `kind` set to `mcp_tool`:
```json theme={null}
{
"method": "tools/call",
"params": {
"name": "registry__search_artifacts",
"arguments": {
"query": "create a ticket",
"kind": "mcp_tool",
"semantic": true,
"limit": 10,
"session_id": "mcp_session_01K…",
"rationale": "Find a tool that files a ticket for the user."
}
}
}
```
| Argument | Required | Meaning |
| - | - | - |
| `query` | Yes | What the tool should do, in plain words. |
| `kind` | No | Set to `mcp_tool` to search only tools. |
| `semantic` | No | `true` matches by meaning instead of by keyword. Defaults to `false`. |
| `workspace_id` | No | Limit results to one workspace. |
| `limit` | No | Results to return. Defaults to 50, up to 500. |
Call [Search the tool catalog](/api/references/api-reference):
```bash theme={null}
curl -X POST "https://api.atlan.com/mcp/v1/tools/search" \
-H "Authorization: Bearer $ATLAN_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "query": "create a ticket", "strategy": "hybrid", "limit": 10 }'
```
| Field | Meaning |
| - | - |
| `query` | What the tool should do. |
| `strategy` | `fts` for keyword, `vector` for meaning, or `hybrid` for both. |
| `workspace_id` | Limit results to one workspace. |
| `is_system_included` | Include Atlan platform tools. Defaults to `true`. |
| `limit`, `offset`, `cursor` | Page through results. |
## Turn a result into a wire name
A search result names the tool and where it runs. The name you call adds a
namespace prefix:
| The result has | Call it as |
| - | - |
| `owner: "registry"` | `registry__` |
| Another `owner`, such as `skill` | `extension____` |
| A `server_id` and no `owner` | `remote____` |
For example, a tool `create_issue` on server `mcp_server_01k7…` is called as
`remote__mcp_server_01k7…__create_issue`.
The live `tools/list` result is the authority for exact wire names and input
schemas on the deployment you are connected to. When in doubt, match the
search result against `tools/list` before calling.
## Call the tool
Send a standard MCP `tools/call` to `https://api.atlan.com/mcp` with the wire
name, the tool's arguments, your `session_id`, and a `rationale`. Before
forwarding the call, the gateway:
1. Confirms that the tool is in the catalog. A tool the gateway has not
discovered cannot be called.
2. Checks your permission. You can see the tools of any server in a workspace
you can read. Running them requires permission to update that workspace.
3. Attaches the server's credential, either the shared credential or your own
connected account.
4. Forwards the call, relays progress and cancellation, and records the
outcome in your session.
## When to search first
| Situation | Approach |
| - | - |
| A few servers, a focused agent | Read `tools/list` once and choose from it. |
| Many servers, or an agent that serves open-ended requests | Search the catalog, then call only the tools that match. |
| An application that picks tools for users | Use the REST search and show the results before calling. |
| An inventory or governance report | Use `POST /mcp/v1/tools/search` or `GET /mcp/v1/tools`. |
`GET /mcp/v1/tools` and the search endpoints read the stored catalog. It can
briefly trail a server that has just changed, so use the live `tools/list`
when you must know exactly what is callable right now.
## Next steps
Every first-party tool, by provider.
Add a server and its tools join the catalog.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.