Summary
ADR-0076 §12 defers MCP tools for the Docs surface,
following the CLI-first deferral ADR-0070 §9, ADR-0071 §11 and ADR-0073 §12
already set. This is the Docs counterpart of #1614 (Sheets), and should
probably be picked up alongside or after it — they share every design
question and the answers should match.
The CLI surface shipped in #1628 and #1639: drive docs info/read (ungated)
and drive docs replace/append/create (gated on docs-write).
What should be easy
The read tools mirror drive_sheets_info/drive_sheets_read almost exactly.
src/mcp/drive_tools.rs already has the shape, and the engines return typed
outcomes that serialize cleanly.
What needs a decision
Should the mutating verbs be exposed at all? #1614 faces the same question
for Sheets, and the answer should be the same for both — it is a decision
about the MCP surface, not about Docs.
Two properties make it safer here than it might look, both worth stating in
whatever decision gets made:
- The gate cannot be bypassed by an MCP caller.
FilesApi's mutating
methods and DocsApi::batch_update are pub(in crate::drive), so a tool
handler physically cannot call them without going through a gated engine.
That is a compile-time property, not a convention.
- Logging cannot be bypassed either.
record_attempt lives inside the
engine rather than the CLI layer, specifically so a future MCP caller still
produces a drivemutation record — including for a Blocked outcome, which
makes zero API calls.
And one that makes it harder:
--dry-run has no natural MCP analogue. A tool call is not a shell
invocation the user inspects before running. Either the preview becomes a
separate tool, or the mutating tools are exposed without one — which
changes the safety story ADR-0076 §7 relies on.
Also worth settling
- Whether
is_stale_revision's outcome needs a distinct machine-readable
shape, so an agent can tell "re-run this" from "this was wrong".
- Whether the occurrence-count estimate should be surfaced at all, given
ADR-0076 §7 makes it display-only and explicitly non-authoritative — an
agent is more likely than a human to treat a number as a fact.
Refs #1615, #1628, #1639, #1614, ADR-0076 §12
Summary
ADR-0076 §12 defers MCP tools for the Docs surface,
following the CLI-first deferral ADR-0070 §9, ADR-0071 §11 and ADR-0073 §12
already set. This is the Docs counterpart of #1614 (Sheets), and should
probably be picked up alongside or after it — they share every design
question and the answers should match.
The CLI surface shipped in #1628 and #1639:
drive docs info/read(ungated)and
drive docs replace/append/create(gated ondocs-write).What should be easy
The read tools mirror
drive_sheets_info/drive_sheets_readalmost exactly.src/mcp/drive_tools.rsalready has the shape, and the engines return typedoutcomes that serialize cleanly.
What needs a decision
Should the mutating verbs be exposed at all? #1614 faces the same question
for Sheets, and the answer should be the same for both — it is a decision
about the MCP surface, not about Docs.
Two properties make it safer here than it might look, both worth stating in
whatever decision gets made:
FilesApi's mutatingmethods and
DocsApi::batch_updatearepub(in crate::drive), so a toolhandler physically cannot call them without going through a gated engine.
That is a compile-time property, not a convention.
record_attemptlives inside theengine rather than the CLI layer, specifically so a future MCP caller still
produces a
drivemutationrecord — including for aBlockedoutcome, whichmakes zero API calls.
And one that makes it harder:
--dry-runhas no natural MCP analogue. A tool call is not a shellinvocation the user inspects before running. Either the preview becomes a
separate tool, or the mutating tools are exposed without one — which
changes the safety story ADR-0076 §7 relies on.
Also worth settling
is_stale_revision's outcome needs a distinct machine-readableshape, so an agent can tell "re-run this" from "this was wrong".
ADR-0076 §7 makes it display-only and explicitly non-authoritative — an
agent is more likely than a human to treat a number as a fact.
Refs #1615, #1628, #1639, #1614, ADR-0076 §12