The tools roster

The big picture draws Tools as two boxes: a general Other tools box every subagent can reach, and nai-analysis, reachable only through the /nai-issue-to-agent bridge. This page is what's actually inside both boxes — pulled straight from each agent's own tools: frontmatter, not a paraphrase — plus the layer above it, where those tools are provisioned, and the layer between, where the harness itself refuses some of them.

Three layers, in order

A tool name in an agent's tools: line is the last of three narrowings, not the only one. Above it sits the server or connector, which decides what exists at all; between them sits .claude/settings.json, which the harness applies before any agent is dispatched. paper-ingester is the only agent file that names the middle layer in its own body, and it states the design intent plainly: “This isn't prose-only: .claude/settings.json denies any mv/cp/curl Bash command whose arguments reference library-wiki...wiki at the permission layer, ahead of execution — a second, structural backstop under this instruction, not a replacement for following it.”

%%{init: {'theme':'neutral', 'flowchart':{'htmlLabels':false,'nodeSpacing':26,'rankSpacing':110}}}%%
flowchart LR
    subgraph L1["1 - server scope"]
        gw["google-workspace (local uvx server)"]
        qo["Qonto (claude.ai connector)"]
    end
    subgraph L2["2 - .claude/settings.json"]
        gwp["no google-workspace entry"]
        qop["9 allow / 53 deny"]
    end
    subgraph L3["3 - agent tools: frontmatter"]
        a1["calendar-briefing (2 Calendar tools)"]
        a2["email-triage (3 Gmail tools)"]
        a3["qonto-collector (9 Qonto tools)"]
        a4["loan-interest-vga (list_transactions)"]
    end

    gw --> gwp
    qo --> qop
    gwp --> a1
    gwp --> a2
    qop --> a3
    qop --> a4

    subgraph GH["beside the layers - no server, no mcp__ prefix, no tools: line"]
        orch["/nai-paper-ingest orchestrator (not a subagent)"]
        cli["Bash, shelling out to the gh CLI"]
        iss["GitHub issue on this repo: 1 view, 1 comment"]
        hook["Stop hook (.claude/settings.local.json)"]
        rem["git push to origin main"]
    end

    orch --> cli
    cli --> iss
    hook --> rem

    classDef provider fill:#e8eef7,stroke:#2b5f9e,stroke-width:2px
    classDef perm fill:#f3e9f3,stroke:#7a3f7a,stroke-width:2px
    classDef subagent fill:#fdf3e0,stroke:#8a5a00,stroke-width:1.5px
    classDef github fill:#e3f0e6,stroke:#2f6b46,stroke-width:2px
    class gw,qo provider
    class gwp,qop perm
    class a1,a2,a3,a4 subagent
    class orch,cli,iss,hook,rem github

Where the tools come from

Two providers supply everything outside this repo, and they are provisioned in two entirely different ways — which is why the prefix in a tool name is worth reading. Neither is in git: “None of these are in the repo — there is no .mcp.json, so every server is user-scoped and a new machine starts with zero. Nothing that touches Gmail, Calendar, or Qonto works until this is done.”

The google-workspace registration is where the whole layering idea is stated outright. The setup doc chose --tools over the server's alternative --permissions SERVICE:LEVEL flag on purpose, “matching the pattern already used here: broad OAuth scopes at the server, narrow enforcement at the subagent tools: whitelist” — and then names the consequence in the same breath: “Note the consequence — --tools ... chat requests the Chat write scopes too, so message-sending tools are exposed at the server level. Any agent that must not post to Chat has to exclude those tools in its own frontmatter, exactly as email-triage excludes send_gmail_message.”

Which Google service is which

“google-workspace” is one server name covering four distinct Google services, and the page-level tool names don't say which is which. The setup doc does, service by service — its own title is “Google Workspace MCP Setup (Gmail + Calendar + Chat)”, and the live registration adds a fourth. Split out, the five granted tools land in exactly two of the four services, and the other two are provisioned but unconsumed.

Chat is the sharpest illustration on this page of “broad OAuth scopes at the server, narrow enforcement at the subagent tools: whitelist”, because the capability is not merely theoretical — it is finished and proven. The server exposes six Chat tools (“28 tools total, 6 of them Chat”), the project-level prerequisite is done (“Chat app configured in the Console (USER)”), and both directions were smoke-tested: “Smoke test passed: list_spaces returns real spaces; send_message posted to the Agents space (spaces/AAQAHnZQMS0) 2026-07-14” and “get_messages verified reading the Agents space 2026-07-14 (output matched the Chat web UI exactly)”. And still no file under .claude/agents/ grants a single Chat tool — a grep for mcp__google-workspace__ across all 25 agent files returns only the three Gmail and two Calendar names. That is a working capability with no consumer, which is exactly what the doc asks for: “The two WRITE tools above are the Chat equivalent of send_gmail_message. Keep them out of the tools: frontmatter of any read-only subagent.” One prerequisite for using them from a session is still open in the doc's own checklist: “[ ] Restart Claude Code so the session picks up the Chat tools natively (until then they are only reachable by driving the server directly)”.

Tool totals for that server come from two probes of two different registrations, and they are not interchangeable: 36 tools with contacts (“uvx workspace-mcp --tools gmail calendar chat contacts, server google_workspace v3.4.4, 36 tools total”) and, without it, “28 tools total, 6 of them Chat”. Changing that list is not free: “Changing the --tools list invalidates the cached token. The token in token_cache.json only carries the scopes consented to at the time it was issued.”

Other tools

The second layer: .claude/settings.json

A subagent's tool grant is not the only thing standing between this fleet and a mutating banking endpoint. .claude/settings.json — tracked in git, unlike the servers themselves — carries a permissions.allow and a permissions.deny list that the harness applies independently of any agent's frontmatter. It is the defence-in-depth layer: even an agent mistakenly granted a write endpoint, or a session driving the connector by hand, meets the deny list first.

So 62 Qonto tool names are written into this one file, and nine of them are reachable. Those nine — get_attachment, get_organization, get_statement, list_client_invoices, list_credit_notes, list_statements, list_supplier_invoices, list_transaction_attachments, list_transactions — are the same nine in qonto-collector's tools: line, tool for tool. The two layers agree here rather than one covering for the other, and that agreement is the point: machine-setup.md describes the division of labour as “the guard that's always on”, with the connector toggle as the removable part. (62 is the count named in this file; no source here states the connector's full catalogue.)

One nuance the file itself settles. machine-setup.md describes the deny list as covering “every Qonto tool the pipeline doesn't use (anything that creates, changes, sends, or approves)”, but the 53 denied names include plainly read-only ones — mcp__claude_ai_Qonto__get_transaction, get_client, get_supplier_invoice, get_label, get_qonto_public_pricing, list_cards, list_clients, list_teams, list_cash_flow_categories among them. The operative rule is default-deny by non-use, not deny-by-write: a read tool the tax pipeline has no need for is denied just the same as a transfer tool.

Keeping Qonto off between quarters

One operational practice is written down, and it applies to the bank connector only: “treat Qonto as off by default, on for the quarterly close”. In full: “Disable it when you're not closing a quarter: in Claude Code, /mcp → select the Qonto connector → disable (or toggle it off in your claude.ai connector settings)”, then “Re-enable it for the close, verify /mcp reports Connected, run /nai-tax-theo, then disable it again.” The machine-setup verification checklist carries the same rhythm: “/mcp reports google-workspace Connected, and Qonto Connected when enabled — then disable Qonto again until the next quarterly close”.

Two reasons are given, and they are worth separating. The first is cost, the second is surface: “Every other session pays the connector's context cost — its tool schemas and server instructions — for nothing, and a connected banking API is surface you don't need while editing prompts or drafting a newsletter.” It is affordable because the consumer set is so small: “Only /nai-tax-theo uses Qonto (the qonto-collector and loan-interest-vga subagents) — /nai-payroll-theodora never touches it.” And the toggle is explicitly not the guarantee — the deny list is: “Independent of this toggle, .claude/settings.json deny-lists every Qonto tool the pipeline doesn't use … so even a connected session only ever exposes the nine read tools … The toggle removes the remaining nine plus the server's instruction block; the deny list is the guard that's always on.”

There is no equivalent practice for google-workspace, and none should be inferred: the only recurring operation documented for it is re-consent when its scope changes. Nor are the server definitions themselves anywhere in git — /nai-cohort-census asks whoever replicates its scan by hand to count “MCP servers in .mcp.json”, and in this repo that field reads zero, because no such file exists.

nai-analysis — a route that isn't a subagent tool

Nothing in the tables above ever touches nai-analysis. That access path exists entirely outside the subagent tools: system, and outside MCP altogether: /nai-issue-to-agent (the orchestrator itself, not a subagent) shells out via Bash to two Node scripts in scripts/issue-bridge/ — fetch-issue.mjs and post-comment.mjs — which hold a Supabase service-role key and talk to nai-analysis's database directly. Both scripts are deliberately narrow: “The service-role key stays in the local, gitignored .env — never committed. fetch-issue.mjs / post-comment.mjs only ever touch the one issue id passed as an argument (no scan/list queries) and only ever insert one row into issue_comments — they never edit an issue's content or status, and never update or delete anything.” That's the whole reason this is drawn as its own box on the big picture instead of folded into “other tools” — it's a different kind of access, at a different layer, held by the orchestrator instead of a subagent, and no permission list or MCP server sits anywhere along it.

GitHub — the same shape, one layer up

GitHub is the second route of exactly that shape, and it belongs on this page for the same reason: it is real, remote, write-capable access that no tools: line anywhere will ever show you. Exactly one command uses it. /nai-paper-ingest reaches GitHub by shelling out through Bash to the gh CLI, twice, both times from the orchestrator: gh issue view <n> --json number,title,body,url,state to fetch the issue, and gh issue comment <n> --body "<summary>" to post the result. There is no MCP server for GitHub in this repo and no agent frontmatter that names it.

The subagent it dispatches never gets near it. paper-ingester does hold Bash — tools: Bash, Read, Glob, WebFetch — but its own boundary spends that grant elsewhere: “Bash is granted for exactly two purposes: curl-downloading a resolved PDF URL to a system temp path, and mv/cleanup to place the downloaded file into work/<Topic>/ and remove the temp copy afterward. Never use it for anything else — no arbitrary shell, no touching any file this process didn't itself just create.” The write into GitHub is held one layer above the agent tools: system, and it is bounded in prose at exactly the point it happens: “Never close the issue, never add/remove a label, never edit its title or body — this comment is the only change you make to the issue.”

GitHub as an input route, not only an output

One issue read and one comment posted is a small surface, and it would be easy to file GitHub under plumbing. What argues against that is the material that travels along it. 11 Blog/blog-ideas.md is the fleet's reading backlog — it opens by saying it is not a draft (“Not a blog post. This is a backlog file. Do not run /nai-document blog-ideas against it”) — and it records where the material comes from and how much of it there is: “Source: Google Chat space Agents (spaces/AAQAHnZQMS0), read 2026-08-08. Nine messages in the space, all posted by Udo; seven carry links, two are hello / hi from setting the space up on 2026-07-14 and are not captured below.” Three of those seven are papers, and the file names GitHub as the way out of the backlog rather than as a filing detail: “Items 3, 6 and 7 are arXiv papers. Filing each as a GitHub issue on this repo routes them through /nai-paper-ingest into the research library, which is a better home for the PDF than this list. Item 7 has already been through it.”

So a GitHub issue on this repo is not only where /nai-paper-ingest reports — it is the documented trigger, the step a human takes to move an item from a backlog line into the research library. The chain has been walked end to end exactly once, and the file says which item: “already ingested. This is the same paper as GitHub issue #18, filed to work/AI/ by /nai-paper-ingest and closed on 2026-08-08. The PDF is in the research library; only the blog post is outstanding.” That is item 7, AgentRadio, arxiv.org/abs/2607.28430 — and the resulting draft is in the repo: 11 Blog/shelf-life-shorter-than-peer-review.md opens “[AgentRadio](https://arxiv.org/abs/2607.28430) makes an unusually clean argument.”

The honest shape is that the route is real and proven, not yet the default. Two more backlog items name /nai-paper-ingest in their own notes — item 3, “Note: paper link — a candidate for /nai-paper-ingest if you file it as a GitHub issue”, and item 6, “Note: paper link — candidate for /nai-paper-ingest” — and both already have drafts in 11 Blog/: nothing-detects-what-was-dropped.md (“A paper came past titled [Agentic Context Management](https://arxiv.org/abs/2607.21503)”) and it-isnt-object-oriented-its-typed.md (“NVIDIA labs published [OO Agents](https://arxiv.org/abs/2607.20709), proposing that an agent should be a Python class.”). All three arXiv items in the backlog reached a draft; only one of the three went through the GitHub issue on the way. The issue step is what puts the PDF in the research library — it is not what produces the post.

The two orchestrator routes look alike and are not the same system, which is worth stating because the wording in one command file invites the mix-up. /nai-issue-to-agent's argument parser says its regex “handles both bare UUIDs and pasted GitHub issue URLs (they contain the UUID)” — but the bridge it calls goes to Supabase, not GitHub: “Bridges nai-analysis issues (Supabase)”. CLAUDE.md draws the line the other way round for the gh route, and just as plainly: /nai-paper-ingest “reads one GitHub issue on *this* repo (not nai-analysis)”. Different host, different credential, different issue tracker, one comment each.

There is a third way this repo talks to GitHub, and it sits outside the tools system altogether: plain git. The repo is cloned from https://github.com/udopnink/nai-os.git, and the Stop hook “auto-commits and pushes to origin main after every turn (retrying once with git pull --rebase --autostash if the push is rejected because the clone is behind…)”. The tracked allow list pre-approves git log *, git add * and git commit -q -m ' * — and carries no git push entry; the push runs from the hook, which lives in that same gitignored .claude/settings.local.json. So of the three GitHub paths, the only one that is fully visible in tracked files is the one that writes the least.