Search mode tools

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.

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.

The first search of a session:

{
  "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:

{
  "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.
`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.

{
  "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.

{
  "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.

CLI

SDK

MCP

API

`mcp__search_tools`

`mcp__describe_tools`

`mcp__call_tool`

See also

​mcp__search_tools

​mcp__describe_tools

​mcp__call_tool

​See also

`mcp__search_tools`

`mcp__describe_tools`

`mcp__call_tool`

See also