ADR: Tool surface granularity and naming #50

New issue

Closed

opened 2026-06-14 19:52:01 +00:00 by james · 0 comments

james commented

2026-06-14 19:52:01 +00:00

Owner

Write an ADR resolving how the agent's tool surface is shaped, before the tool-surface ticket lands.

Scope — the ADR must answer

Granularity. Coarse REST-shaped tools (get_people, create_person, update_person, delete_person) vs domain-shaped tools (find_people_at_org, link_person_to_org, add_note_to_person, merge_people). Coarse is fewer tools and more reasoning load on the agent; fine is more tools but more deterministic behaviour. Pick a default; allow both within the surface where appropriate.
Naming convention. verb_noun (snake_case) vs noun.verb. Convention matters for discoverability in MCP clients and for consistency across entity types.
Write-tool shape. Write tools return a "proposed change" object rather than mutating. Define the shape of that object — what fields it carries, how the agent describes it, how the PWA renders it, how the commit endpoint accepts a confirmed proposal.
Destructive-vs-safe classification. Every write tool tagged on a small enum (safe_create, safe_update, destructive_update, destructive_delete). The UI uses the tag to escalate the confirmation prompt.
Discovery. How an MCP client lists what's available — exhaustive tool list at handshake vs categorised vs paginated. Affects token cost of using Carol as an MCP server.
Cross-user safety. Per-user scoping is non-negotiable, but the ADR records where the scope is enforced (the repository layer, not the tool layer) and why tools are forbidden from accepting a user_id parameter.

Follow the ADR format in docs/adr/0001-record-architecture-decisions.md.

Acceptance criteria

ADR written and accepted, covering every bullet in Scope.
ADR linked from docs/adr/README.md.
No code in this ticket — pure design. The tool surface ticket implements against this ADR.

Part of epic #47. Should land before the Domain tool surface ticket.

Write an ADR resolving how the agent's tool surface is shaped, before the tool-surface ticket lands. ## Scope — the ADR must answer - **Granularity.** Coarse REST-shaped tools (`get_people`, `create_person`, `update_person`, `delete_person`) vs domain-shaped tools (`find_people_at_org`, `link_person_to_org`, `add_note_to_person`, `merge_people`). Coarse is fewer tools and more reasoning load on the agent; fine is more tools but more deterministic behaviour. Pick a default; allow both within the surface where appropriate. - **Naming convention.** `verb_noun` (snake_case) vs `noun.verb`. Convention matters for discoverability in MCP clients and for consistency across entity types. - **Write-tool shape.** Write tools return a "proposed change" object rather than mutating. Define the shape of that object — what fields it carries, how the agent describes it, how the PWA renders it, how the commit endpoint accepts a confirmed proposal. - **Destructive-vs-safe classification.** Every write tool tagged on a small enum (`safe_create`, `safe_update`, `destructive_update`, `destructive_delete`). The UI uses the tag to escalate the confirmation prompt. - **Discovery.** How an MCP client lists what's available — exhaustive tool list at handshake vs categorised vs paginated. Affects token cost of using Carol as an MCP server. - **Cross-user safety.** Per-user scoping is non-negotiable, but the ADR records *where* the scope is enforced (the repository layer, not the tool layer) and why tools are forbidden from accepting a `user_id` parameter. Follow the ADR format in `docs/adr/0001-record-architecture-decisions.md`. ## Acceptance criteria - [ ] ADR written and accepted, covering every bullet in Scope. - [ ] ADR linked from `docs/adr/README.md`. - [ ] No code in this ticket — pure design. The tool surface ticket implements against this ADR. Part of epic #47. Should land before the Domain tool surface ticket.

james added the

area:service

label

2026-06-14 19:52:49 +00:00

james referenced this issue from a commit

2026-06-28 19:44:44 +00:00

docs(adr): ADR-0030 agent tool surface granularity and naming

james referenced this issue from a pull request that will close it,

2026-06-28 19:44:58 +00:00

docs(adr): ADR-0030 agent tool surface granularity and naming #328

james closed this issue

2026-06-28 19:52:15 +00:00