> ## 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 SDK. To install or publish skills from a terminal, use the `aireg` CLI; `aireg --map json` prints its command map. The `atlanai` CLI is deprecated. 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.
> These docs cover Atlan AI Registry, Atlan's hosted product. The AI registry specification and aireg CLI are maintained separately. /open-source lists publicly reachable signed installers and explains that the source repository and hosted CLI reference currently require GitHub access. Do not claim the repository or its reference docs are publicly accessible. Use these docs for Atlan-specific setup such as the adapter, sign-in and workspaces.

# Search mode tools

> Arguments, results, and examples for mcp__search_tools, mcp__describe_tools, and mcp__call_tool, the three tools a search-mode connection lists.

By default, a connection to `https://api.atlan.com/mcp` lists these three tools instead of the full catalog. A connection with `?tools=full` lists the full catalog instead. To learn when to use search mode, see [How search mode works](https://platform.atlan.com/gateway/mcp/concepts/search-mode.md).

| Tool | Effect | Use |
| - | - | - |
| `mcp__search_tools` | Read only. The first search opens a session. | Find the tools for one step of a task. |
| `mcp__describe_tools` | Read only | Get the schema of a tool you know by name, or list a server's tools. |
| `mcp__call_tool` | Whatever the tool it runs does | Run one tool. |

`mcp__search_tools` and `mcp__describe_tools` return JSON in a `text` content block. `mcp__call_tool` returns the tool's own result unchanged.

## `mcp__search_tools`

Finds the tools you can call for one step of a task.

| Argument | Type | Required | Meaning |
| - | - | - | - |
| `query` | string | Yes | What you need right now, in one sentence, naming the app if you know it. Kept to 500 characters. Stored with the session, so keep credentials and customer data out. |
| `objective` | string | On the first search | What the whole session is for, in one sentence, for the person who reads the audit trail. Ignored once a session exists. |
| `session_id` | string | No | The session the first search returned. A search without one opens a new session. |
| `limit` | integer, 1 to 20 | No | How many tools to return. Defaults to 5. |
| `detail` | `schema` or `summary` | No | `summary` returns names and descriptions without input schemas. Defaults to `schema`. |
| `servers` | 1 to 20 strings | No | Search only these servers, by readable name, such as `["linear", "slack"]`. See [Scope a search to some servers](https://platform.atlan.com/gateway/mcp/concepts/search-mode.md#scope-a-search-to-some-servers). |

The first search of a session:

```json theme={null}
{
  "method": "tools/call",
  "params": {
    "name": "mcp__search_tools",
    "arguments": {
      "query": "create a Linear issue for a failing invoice pipeline",
      "objective": "Triage this week's failed invoice pipeline runs and file one issue per root cause."
    }
  }
}
```

The result:

```json theme={null}
{
  "session_id": "mcp_session_01k7z9m2c8x4f6h0j2n4p6r8t0",
  "tools": [
    {
      "name": "linear__save_issue",
      "server": "linear",
      "description": "Create or update an issue",
      "input_schema": {
        "type": "object",
        "properties": { "title": { "type": "string" } },
        "required": ["title"]
      }
    }
  ],
  "connect": [
    {
      "server": "github",
      "provider": "github",
      "reason": "never_connected",
      "note": "Ask the user to connect their account for this server, then search again."
    }
  ],
  "next": "Run a tool with `mcp__call_tool`, passing its `name` and `arguments`, and this `session_id` (and a `rationale` if `mcp__call_tool`'s schema lists one) beside them at the top level."
}
```

| Field | When it appears | Meaning |
| - | - | - |
| `session_id` | The search has a session | Pass it on every later search, describe, and call. |
| `tools` | Always | Matching tools. Each has `name` and `server`, and when known `title`, `description`, `annotations`, `_meta`, and, unless `detail` is `summary`, `input_schema`. |
| `connect` | A match is on a server you have not connected | One entry per server, with `server`, `provider`, `reason`, and `note`. See [Servers you have not connected](https://platform.atlan.com/gateway/mcp/concepts/search-mode.md#servers-you-have-not-connected). |
| `partial` | A server did not answer | A sentence saying a tool may be missing. Search again later. |
| `next` | Always | What to do next. |

## `mcp__describe_tools`

Returns the full definitions of tools you already know by name, or of every tool on the servers you list. Pass `names`, `servers`, or both. A describe does not open a session, so call `mcp__search_tools` first to get a `session_id` before you call a tool.

| Argument | Type | Meaning |
| - | - | - |
| `names` | 1 to 20 strings | Exact tool names, as `mcp__search_tools` returns them. |
| `servers` | 1 to 20 strings | Readable server names. Without `names`, returns every tool of those servers you can call, up to 100. |
| `session_id` | string | Optional. A describe answers without a session. |

```json theme={null}
{
  "method": "tools/call",
  "params": {
    "name": "mcp__describe_tools",
    "arguments": {
      "names": ["linear__save_issue"],
      "session_id": "mcp_session_01k7z9m2c8x4f6h0j2n4p6r8t0"
    }
  }
}
```

The result has the same `tools` and `next` fields as a search. It can also include:

* `errors`: one `{name, error}` entry for each name it could not describe. An unknown name, or a tool you cannot call, is reported as not a tool you can call; search for it instead. A known tool outside the `servers` you listed is reported as not on those servers; drop `servers` or add that tool's server.
* `truncated`: a sentence saying `servers` alone matched more than 100 tools. Name fewer servers or pass `names`.

## `mcp__call_tool`

Runs one tool and returns its result unchanged. The gateway applies the same permission check, credential, rate limit, and audit record as a direct call.

| Argument | Type | Required | Meaning |
| - | - | - | - |
| `name` | string | Yes | The exact tool name from a search or describe. It cannot be one of the three search mode tools. |
| `arguments` | object | Yes | The tool's own arguments, matching its input schema. |
| `session_id` | string | Yes | The session your first search returned. Put it at the top level, never inside `arguments`. |
| `rationale` | string | When the schema lists it | Why you are making this call, in one sentence. Put it at the top level. It is recorded with the call and never blocks it. |

```json theme={null}
{
  "method": "tools/call",
  "params": {
    "name": "mcp__call_tool",
    "arguments": {
      "name": "linear__save_issue",
      "arguments": { "title": "Invoice pipeline fails on currency rounding" },
      "session_id": "mcp_session_01k7z9m2c8x4f6h0j2n4p6r8t0",
      "rationale": "Filing the root cause I found so the owning team can fix it."
    }
  }
}
```

`mcp__call_tool` is marked as a tool that can change data and reach outside Atlan, because your client cannot see which tool runs underneath. An approval of `mcp__call_tool` in your client covers every tool you can reach. Do not retry a call that changes data automatically; check whether the first attempt completed.

For refusals such as `session_id is required`, see [Search mode errors](https://platform.atlan.com/gateway/mcp/troubleshooting.md#search-mode-errors).

## See also

* [How search mode works](https://platform.atlan.com/gateway/mcp/concepts/search-mode.md): Sessions, server scoping, connect prompts, and approvals.
* [Connect client to MCP Gateway](https://platform.atlan.com/gateway/mcp/how-tos/connect-a-client.md): Client setup, and full mode.
* [All MCP tools](https://platform.atlan.com/tools/mcp/references/tool-catalog.md): The tools a search can find.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.