49 lines
2.6 KiB
Markdown
49 lines
2.6 KiB
Markdown
---
|
|
status: graduated
|
|
initiated: 2026-10-03
|
|
touches: [the console, 03-DESIGN/01-to-be/34-the-console.md, the tool runtime, seats, assignments]
|
|
became: [02-DECISIONS/0195-the-meshs-tools-are-found-by-address-not-announced-whole.md, 03-DESIGN/01-to-be/34-the-console.md]
|
|
---
|
|
|
|
# 021 — Finding a tool in the mesh
|
|
|
|
## What was investigated
|
|
|
|
How an agent finds the one tool it needs among everything the mesh answers, and how a call names
|
|
exactly what it asks — a role the mesh holds once, a role every machine holds, or one assignment of a
|
|
module on one machine — rather than receiving the whole catalogue and a name that can mean several
|
|
things.
|
|
|
|
## Why
|
|
|
|
The operator's observation on 2026-10-03: *Claude should not see all tools at once; they should be
|
|
discoverable — and `postgres.list_databases` is wrong, asking one machine's postgres is not asking
|
|
another's.* Measured the same day from the console's own answer:
|
|
|
|
| | |
|
|
|---|---|
|
|
| tools announced to every session at its start | 228, in 110 KB |
|
|
| names (module or seat prefixes) | 43 |
|
|
| node seats' verbs, which require `node` | 22 |
|
|
| modules with tools on more than one machine | 4 — fail2ban, nftables (every machine), postgres, mssql (two each) |
|
|
| modules reported "not answering", most with no tools and several retired | 47 |
|
|
|
|
The two stateful modules on two machines are listed **once**, with `node` optional and *whichever
|
|
answers* when it is left out — though their two instances hold different databases. Design 34 §3 says
|
|
such a module is listed once per machine; the live console does not do that. The list is taken once
|
|
per session, so a tool that arrives later is invisible until the client reconnects. And only Claude
|
|
Code's own deferral of long tool lists keeps the 228 from the model's context; another MCP client
|
|
would receive them whole.
|
|
|
|
## Options
|
|
|
|
1. **Keep the flat list; rely on the client to defer it.** Rejected: a property of one client, and it
|
|
leaves the ambiguity and the stale list.
|
|
2. **One flat tool per assignment** (`ace_postgres_list_databases`). Removes the ambiguity, multiplies
|
|
the list, and runs into the API's tool-name limit (letters, digits, `_`, `-`, 64 characters).
|
|
3. **A small fixed set of tools that walk the mesh's own structure**, with the full address as an
|
|
argument: the mesh's seats; a machine's node seats and assignments; a search; a description; a
|
|
call. Chosen — see [ADR 0195](../../02-DECISIONS/0195-the-meshs-tools-are-found-by-address-not-announced-whole.md).
|
|
4. **MCP resources or prompts for discovery.** Clients support them unevenly, and an agent acts
|
|
through tools; a resource it cannot be relied on to read is not a discovery path.
|