Home › Answers › tools/list is empty

tools/list is empty: six causes and how to tell them apart

First: which kind of empty?

Gateway builtins — whoami, list_cortex_resources, read_cortex_resource, report_missing_capability, list_cortex_tickets — are always listed and never scope-filtered, because they belong to the gateway rather than to any federated application. That property turns a vague symptom into a two-way branch:

Cause 1 — your token does not carry the scope (most common)

A gateway filters the catalog by exact string match between the scope a tool declares and the scopes in the caller's token. A tool requiring mcp:docs:read is removed from tools/list for a token that does not hold it — silently, and on purpose.

The silence is the feature. Least privilege means an agent must not even learn that a tool exists if its user may not call it. So there is no warning, no 403, no log line saying "hid 14 tools". And because the comparison is literal, mcp:docs:read and mcp:docs.read are two unrelated scopes: a single character makes an entire application vanish.

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"whoami","arguments":{}}}

whoami returns the scopes your token actually carries, next to the scopes each backend expects. Compare the two strings before suspecting anything else — this is the answer four times out of five.

If the scope is genuinely missing, the fix is at the authorization server: the consent screen must offer it and the client must request it.

Cause 2 — a header narrowed the catalog

Cortex Gateway accepts X-Cortex-Backends to restrict tools/list to a subset of applications, which cuts 50–80 % of the context an agent spends on tool definitions. A subtlety bites: an empty value is not "no filter".

X-Cortex-Backends: docs,billing   → tools of those two apps, plus builtins
X-Cortex-Backends:                → builtins only
(header absent)                   → every healthy backend

A client that always sets the header, from a config value that happens to be an empty string, ends up asking for nothing and getting exactly that. Same for X-Cortex-Tool-Mode: search, which does not empty the list but returns compact entries — names and one-line descriptions, with schemas fetched on demand through find_tools. An agent expecting full inputSchema objects may read that as "no usable tools".

Cause 3 — the gateway just booted

The federated catalog is built by polling each backend's list_tools, and it lives in memory. On a cold start the first refresh has not completed yet, so the catalog is empty and tools/list legitimately returns only the builtins. It fills within one refresh cycle — sixty seconds — and pushes notifications/tools/list_changed to connected clients.

Before diagnosing anything else after a deploy or a restart: wait one cycle. A surprising share of "the tools disappeared" reports are a screenshot taken twenty seconds after pm2 restart.

Cause 4 — a backend is down, and that is not an error

When a backend fails to answer list_tools, it loses its tools from the catalog and the refresh continues. This is failure isolation: one broken application must not take down the tool list of the other four. The consequence is that a backend outage looks exactly like a scope problem from the agent's side — tools quietly absent, no error anywhere.

Two things distinguish them. whoami aggregates the health of every backend, so a missing entry there points at the backend, not at your token. And the gateway logs the refresh outcome per backend at every cycle, which names the failure directly.

A related trap: a backend id declared in CORTEX_BACKENDS with no matching CORTEX_BACKEND_<ID>_URL is silently skipped. It never appears, never errors, and looks identical to a backend that is down.

Cause 5 — the backend rejected the discovery token

Catalog discovery does not run as a user. The gateway calls list_tools with a static technical token that carries no email and no role, precisely so a compromised catalog call cannot read anyone's data — and the backend contract requires every other method to be refused when authentication comes from that token.

Implement that rule slightly too broadly and the backend refuses list_tools as well. The gateway receives a 403, treats the backend as unhealthy, and drops its tools. You then debug scopes for an hour while the real problem is a backend that will not describe itself.

Reproduce it directly, with no gateway involved:

curl -s -X POST https://docs.internal.example.com/api/cortex/backend \
  -H "Authorization: Bearer $CORTEX_TECHNICAL_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"method":"list_tools","params":{}}' | jq

This must return the catalog. The same call with {"method":"list_notes"} must return 403. If the first is refused, or the second succeeds, the backend has the rule backwards. Details in the backend contract, and the surrounding design in exposing a REST API as an MCP server.

Cause 6 — one tool is missing, not all of them

Three candidates, in order:

• Scope. Same as cause 1, restricted to one tool. Write tools are the usual victims: a read-only token sees list_notes but never save_note. That is the system working.
• Name collision with a builtin. Every backend exposes whoami by contract, so a federated docs_whoami would duplicate the gateway builtin. The gateway masks it from tools/list — the builtin already aggregates every backend's answer, and takes priority at dispatch.
• Deprecated, not absent. A tool marked deprecated is still listed, with its removal date prefixed into the description. Agents that filter on description text have been known to drop them.

The chicken-and-egg you will hit exactly once

The scopes_supported field of /.well-known/oauth-protected-resource is derived from the live catalog: ship a tool with a new scope in any backend and that scope becomes discoverable without touching the gateway. Elegant — and it means that on a cold boot, or when every backend is unreachable, the document advertises no scopes at all.

A client reading it at that exact moment requests no scopes, receives a token that grants none, and sees a catalog filtered down to the builtins. Everything then looks like cause 1, and re-authenticating fixes it, which teaches you nothing. The rule that saves the hour: after any restart, let one refresh cycle pass before you let a client run discovery.

The diagnostic, in order

The hosted demo is a working reference: connect an agent, call whoami, and compare a read-only token's tools/list with one that also holds the write scope. The write tools are not forbidden — they are invisible, which is what least privilege looks like from the agent's side.

FAQ