tools/list

List the tools a gateway exposes to you.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Pass params.cursor to fetch a later page. Pages hold 50 tools; the cursor is an opaque offset returned as nextCursor.

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "web_search",
        "description": "Search the web",
        "inputSchema": {
          "type": "object",
          "properties": { "query": { "type": "string" } },
          "required": ["query"]
        },
        "annotations": { "readOnlyHint": true },
        "_meta": { "dev.noorle/autonomy": { "outcome": "allow" } }
      }
    ],
    "nextCursor": "50",
    "ttlMs": 300000,
    "cacheScope": "private"
  }
}

Field	Description
`tools[].name`	The namespaced wire name
`tools[].description`	Human-readable description
`tools[].inputSchema`	JSON Schema for the arguments
`tools[].annotations.readOnlyHint`	`true` when the tool is read-tier
`tools[]._meta["dev.noorle/autonomy"]`	Static autonomy outcome — see below
`nextCursor`	Present when more pages remain
`ttlMs`	How long the response may be treated as fresh
`cacheScope`	Always `"private"`

Tool names

The wire name is {namespace}_{tool} — one underscore, no double underscore. The namespace comes from the capability’s namespace field, which is unique per account.

Capability	Example
Files built-in	`file_read`, `file_write`, `file_ls`
Web Search built-in	`web_search`
Code Runner built-in	`run_python`, `run_javascript`
Memory built-in	`memory_store`, `memory_recall`, `memory_forget`
A plugin named `my-plugin`	`my_plugin_{tool}`
A connector	`{connector_namespace}_{operation}`

Do not assume a namespace from the capability’s display name — read it from GET /v1/capabilities.

Caching

cacheScope is private on every gateway, always — never public. The response is a function of the calling principal, not just the gateway. Two callers on one gateway legitimately receive different lists: autonomy annotations are computed per caller, and since workspace-anchor withholding landed, so is the membership of the list. A shared cache could serve an authenticated caller’s fuller tool list to an anonymous one. ttlMs is 300000 (5 minutes). It is a freshness hint, not a snapshot guarantee — the list may change before it expires, and pages carry no cross-page consistency guarantee. Because no list_changed notification is ever sent, this TTL is the only staleness signal a client gets. Staleness never grants authority. A stale allow annotation is a hint that the gate re-evaluates at dispatch and can still deny. Clients on protocol versions before 2026-07-28 receive both fields and will simply ignore them.

Withheld tools

Some tools cannot function without a workspace anchor. On an MCP gateway, an anonymous caller has no anchor, so those tools are removed from the list entirely rather than advertised and then failed at call time. They are also removed from the discovery corpus, so they are not callable by name either.

Built-in	Requires an anchor
Files	All tools
Sandbox	All tools
Browser	`screenshot`, `pdf`, `snapshot` only
Everything else	No

Browser’s markdown, content, extract_json, scrape, and links work sessionlessly and stay listed. Guessing a withheld tool’s name and calling it returns an invalid-tool-name error — the same shape as a tool that does not exist, so the response does not confirm it is there.

Autonomy annotations

Each capability tool carries its static autonomy verdict:

"_meta": { "dev.noorle/autonomy": { "outcome": "deny" } }

`outcome`	Meaning
`allow`	Will execute autonomously under the current policy
`deny`	Will deterministically deny — do not offer this tool to a model
`may_deny_on_args`	An argument-predicated rule applies; no static verdict exists
`ungated`	The gateway has no policy; calls ride the pre-policy path

Two properties to design around:

Denied tools stay listed. Omitting them would churn the surface on every policy edit and hide deliberate “exposed but never autonomous” intent.
No reason is on the wire. tools/list is reachable unauthenticated on public gateways, and the reason would name the account’s policy internals.

Meta-tools (the discovery and unified surfaces) are not namespaced capability tools and pass through unannotated. If the gateway cannot read the policy, the capability list, or the deny ledger, tools come back unannotated rather than annotated from partial inputs. Treat a missing _meta entry as “unknown”, never as “allowed”.

Presentation modes

A gateway renders its tools in one of four modes, set per gateway:

Mode	Behavior
Direct	Every bound tool appears flat in the list
Discovery	Three meta-tools (`discover_tools`, `get_tool_schema`, `execute_tool`) stand in for the corpus
Unified	One `unified_tool` stands in for the corpus
Adaptive	Direct below 30 bound tools, Discovery at or above

Adaptive is the platform default. In Discovery and Unified modes the underlying tools are not directly callable — reaching them goes through the meta-tool.

Errors

Code	Cause
-32029	Rate limit exhausted — this method shares the 600/minute budget with `tools/call`

Missing or invalid credentials fail during transport authentication, before this method runs — see Authentication.

Overview

REST API

MCP Protocol

A2A Protocol

Noorle CLI

Request

Response

Tool names

Caching

Withheld tools

Autonomy annotations

Presentation modes

Errors

​Request

​Response

​Tool names

​Caching

​Withheld tools

​Autonomy annotations

​Presentation modes

​Errors

​Related

Request

Response

Tool names

Caching

Withheld tools

Autonomy annotations

Presentation modes

Errors

Related