What the agent reads

The agent does not have access to your infrastructure: it has access to a set of read tools, and each one is a specific question the RootPilot Agent knows how to run inside your infra.

There are a few hundred of them today, and the number changes with every release — which is why this page does not list them. A hand-pasted list would rot on the first deploy and start lying to you. What this page does is explain how the surface is decided, and how to discover yours.

The surface is not fixed — it depends on your fleet

This is the central concept, and the easiest one to get wrong. Two organizations running the same RootPilot see different sets of tools.

The reason is simple: a tool that needs your infra is only announced if some catalog operation it executes is being served by an Agent connected right now. With no Kubernetes connector configured, pod reads do not exist for the model. With Grafana instead of Datadog, metric reads still exist — because the operation is the same; what changes is who answers it.

The exception sits on our side: a tool that answers from what has already been learned about your environment (recorded topology, notes, the resource graph, fleet health itself) asks your infra nothing, so it is never hidden — it keeps answering with the whole fleet offline.

That turns your question from “does the product have X?” into “does my fleet serve X?”.

The gate is deliberately conservative, and it is worth knowing how:

It hides only on positive knowledge. If we do not know what the fleet serves (empty fleet, an older Agent that reports no connector at all), the surface shows in full instead of disappearing.
It follows health, not just presence. A connector whose credential stopped working drops out of the served set, and tools that depended only on it disappear — the same event fleet health reports.
A composite analysis that crosses several signals shows up if any of them is served, and degrades by saying what was missing. Hiding it entirely would be worse than delivering it partial and honest. The exception is the input operation, without which the analysis never starts: that one makes it disappear, instead of being announced only to fail later.
The set is decided when the session opens. A connector that comes back mid-investigation appears in the next session, not in that one.

If a hidden tool is called anyway, the refusal is immediate and names the operations nobody serves — instead of sending the agent off to connect somewhere there is no credential.

Discovering what your fleet serves

Three surfaces, answering different questions:

Where	What it answers
`tools/list`, from your own client	What this session can call. The authoritative answer, already filtered by your fleet.
The `check_fleet_health` tool	Why something is missing: connector by connector, the state right now.
The Catalog page in the control plane	What the product has, regardless of your fleet. Useful to see what would exist if you connected a source.

check_fleet_health is the one worth learning to read, and it is among the tools announced from the start of the session precisely so it can serve as preflight. Its vocabulary:

State	Meaning
`up`	Served and healthy
`degraded`	Served, with part failing or coverage incomplete
`down`	Served, and every server erroring — typically a credential
`unchecked`	Served, but with no credential probe — this connector does not expose one
`not_configured`	The Agent knows the integration and has no credential for it (secret missing)

Two readings that save you a wrong investigation: unchecked is not “the probe is overdue”, it is a connector that ships no probe at all — waiting will not change the value; and freshness belongs to the whole rollup (checked_age_seconds, at the top of the answer), not to each connector.

Beyond the connectors it returns a verdict about the whole fleet. A fleet with no Agent connected does not look like a healthy one: it says so in a field of its own, because three empty lists would look exactly like “all good, nothing degraded”.

`search_tools`: announce everything, or discover on demand

Announcing a few hundred tools takes a large slice of the model’s context before it does anything. There is an alternative mode, off by default:

Off (default). tools/list announces the whole surface your fleet serves. Simple, compatible with any client.
On. tools/list announces only a curated core plus the search_tools meta-tool. The agent searches for what it needs, the matches become callable in that session, and the server emits tools/list_changed so the client refetches the list.

That is the trade-off: the on mode saves context and costs a discovery round-trip — and it requires a client that understands tools/list_changed. A client that ignores the notification will not see the discovered tools in tools/list (the search result itself names them, so the model can still call them). That is why the default is the simple mode.

Search respects the same gate: it will not offer as “available now” a tool your fleet cannot execute.

Atomic reads and composite analyses

The surface has two kinds of tool, and the difference is altitude:

Atomic reads answer one question against one source: a service’s metrics, a window of logs, an account’s security groups.
Composite analyses answer an investigation question by crossing many reads: investigate this incident, how is production, what is the blast radius if this resource goes down.

What you gain by asking for the composite instead of stitching the atomic ones by hand is not just convenience. It is the correlation across sources (the deploy that coincides with the drop, the topology neighbour that explains the latency) and, above all, coverage accounting: the composite knows how many sources should have answered and reports the ones that did not. Nineteen loose reads do not add up to that property on their own.

The session opens with context

Besides the tools, at session open the server hands the model a short context derived from what has already been learned about your environment: observed topology, quirks already recorded, and — when they exist — your organization’s policy and which observability backend actually serves your fleet.

That last item sounds like a detail and is not: without knowing that SigNoz, not Datadog, is answering, the model writes queries in the wrong dialect and gets errors back. Saying it up front is cheaper than letting it find out by trial.

Answers say what they could not see

This is the product’s most distinctive property, and probably the least obvious on a first read.

Every answer carries a _sources field: which sources it came from, and what state each one answered in. The vocabulary is closed, and each word declares which of four classes it falls into: a read, a deliberate choice not to ask, an inability to ask, or blindness. From there, the shape of the answer changes:

Blind source — the body is discarded. If every source that should have answered failed, the answer does not come back with zeros: it comes back as an envelope, with visibility: "none", error: "no_visibility" and a warning naming the sources. Even the prose goes, since prose is exactly the part that would lie. What survives is the diagnosis and the arguments the read was made with — because discarding the body cannot cost you knowing what we went blind about.
Partial coverage — the body stays, annotated. When there is real data it comes back, with visibility: "partial" and an accounting of what was missing.
Empty never becomes zero. A count that came from an operation that did not answer is null, not 0.
Absence requires proof. Claiming something does not exist requires a read that actually happened. Without it, the result is inconclusive, and says so.

The first two rules are structural: they hold at a single point, the one every answer passes through. The last two are the discipline each tool keeps inside its own body — that is the difference between a guarantee about the shape and a rule about the content, and it is worth knowing so you know what to check when a number looks too good.

The same reasoning governs verdicts: a grade, a classification, a “this is fine”. Where a grade comes from penalties, a failed read would improve the number — so the grade is simply not emitted when a source went blind, and what was observed comes back marked as partial. Total blindness discards the verdict along with the body; under partial coverage, holding the conclusion back is each tool’s job.

Reads have a scope, and it is stated

In the cloud, every read happens inside an account (or project, or tenant). Which one was read travels back in the answer on every cloud, and that is not decoration: an Agent pointed at the place where almost nothing lives is indistinguishable from an empty account, unless someone says where it looked. On AWS the region comes back too, for the same reason.

When more than one account is routable, the tool asks you to choose, or accepts sweeping all of them at once ("all"). Two caveats worth having before you trust a sweep:

On AWS, it declares what it did not sweep — known accounts beyond the fleet’s reach are named and visibility drops to partial. Four out of fifteen accounts is never a complete answer. On GCP and Magalu that accounting does not exist yet: the sweep covers what the fleet serves, without enumerating what was left out.
The sweep stops at 12 accounts. The rest come back listed as skipped, with the reason — they do not vanish.

Taking reads off the surface

Not every read has to be granted. The tool denylist is how you say “you may read my metrics and my logs, but not my security groups” — composed by you, enforced by the Agent inside your infra.

What happens to the surface when you deny something:

Tools that depended only on the denied operations disappear — from the announcement and from execution.
Those that depended on them in part carry on, degrading, and the answer carries a note that policy removed part of what it would have seen.
Suppression is legible: the denied source is reported as denied_by_policy, which counts as I could not read and never as it does not exist. “Policy forbade me” is not proof of absence — and that distinction is why the denylist is not a silent subtraction.

The session also knows about the policy before it needs it, so the answer to a question in a denied area is “that is disabled by your organization’s policy” rather than “I found nothing”. What it knows is the policy the Agent announced back — one you composed and never deployed does not show up there, and that is why the Fleet shows draft and applied side by side.

What this page does not cover

The list of tools. By decision: it is discovered, not documented — see how to discover.
Writing. The four exceptions and the gates covering them are in what the agent writes.
What is redacted before anything leaves your infra — PII redaction.