rea/docs/tool-design.md

MCP tool design

Decide whether to add a tool

Design around the analyst question. Inspect the current canonical contracts, provider capabilities, and nearest existing tool before changing the surface. Extend a tool when intent and result contract match; add one for a distinct outcome or materially different authority. Public names and semantics remain provider-neutral, with exact coverage reported per provider.

Keep the catalog complete; report capability/session availability instead of truncating schemas. Serialized bytes alone do not establish agent usability.

Choose the tool shape

Shape	Use it for	Result
inspect	Facts about one target, object, or resource	Relevant fields, locations, and facet availability
search / list	Candidate discovery	Stable ordering and context; pagination when the query or format needs it
trace	Relationships across evidence	Typed edges, supporting facts, and unresolved paths
compare	Explicitly paired artifacts or observations	Identity, comparable coverage, and supported deltas
workflow	A recurring outcome needing composition	Inline answer, contributing evidence, and partial facets
observe / capture	Runtime behavior	Authority, launch/attach effects, lifecycle, and cleanup status

These are task shapes, not mandatory prefixes. Name tools for the action and object callers reason about. Avoid unrelated discovery/execution/mutation modes inside one tool.

Prefer primitives; compose workflows

A primitive reports a reusable fact about an identified object or relationship. A format-specific decoder qualifies; one application's business interpretation belongs outside the general contract. Expose provider APIs when they add a useful capability that existing tools cannot express.

Compose a workflow when repeated use demonstrates a multi-source outcome REA can join without hiding caller choices or uncertainty. Batch homogeneous reads when that removes repeated work while preserving per-item outcomes. Keep prompts optional and avoid prescribing call sequences that a direct tool can replace.

Agents can compose experiments with ordinary commands, scripts, and local fixture servers. Custom orchestration languages, replay engines, or separate prepare/execute plans need an observed requirement those primitives cannot satisfy. A plan without execution does not establish runtime behavior.

Define the contract

• Use strict inputs with explicit target identity and required fields. Preserve meaningful target, action, capture, and output choices; remove ignored options and repeated permission declarations.
• Return the requested facts inline with artifact/provider identity, source locations, Evidence references, coverage, and relevant confidence and limitations. Use supported selection, summaries or views when they answer the question; preserve access to complete source Evidence and honor existing contracts and requested detail. Missing coverage is unknown, not absence. Avoid extra lookups solely to understand the answer or its provenance.
• Keep observed, derived, and inferred relationships distinct. Preserve unresolved edges and partial provider facts instead of requiring every provider to supply the same metadata.
• For caller/callee reads, relationship_coverage describes only the provider-observed direct relationship set. complete means that set was returned without a known read limit; it does not claim every possible runtime edge. Provider and execution caveats stay in limitations and do not imply incomplete relationship coverage. Missing coverage remains unknown.
• Declare process, filesystem, network, UI, and mutation effects truthfully; enforce the requested target and lifecycle.
• Add limits only for real format, protocol, authority, or measured resource constraints. Report pagination, truncation, cancellation, and partial failure. An assumed agent budget is insufficient justification for a limit.

Own the lifecycle

For tools that acquire resources, identify the owner and the observations that establish each transition. Include temporary files and one-shot commands, as well as persistent engine sessions. Use the existing provider contracts; providers need not expose identical state machines.

• Keep target admission, provider readiness, active work, observed process exit, and resource release separate. A valid process handle, successful launcher, or selected target establishes only its own fact. Publish available identity and exit observations even when launch fails; retain unknown ownership.
• Authenticate and capture identity through the same boundary on initial and recovery handshakes. Bound abandoned unauthenticated listeners where the protocol permits it; that deadline must not expire authenticated idle sessions or long-running native work. Listener expiry does not prove target closure.
• Readiness observations may await owned prerequisite commands. Status must remain readable during owner finalization without starting replacement work; report readiness as unknown when it cannot be re-observed.
• Shared startup has one producer and independently cancellable caller waits. Keep it running while any caller still needs it. The final departing caller waits for owned cleanup and retains its failure. Provider closure is distinct from caller cancellation. Retained cleanup capabilities block replacement; derive readiness from the current startup's completion and live connection.
• For cancellable observations, carry cancellation through result consumption and awaited cleanup. Before returning success, check the signal after the last awaited finalization step. Retain collected observations under typed cancellation. Preserve an existing primary failure and let incomplete cleanup retain its own classification. Preserve the caller's abort reason as the typed cancellation error's cause, including when cancellation is observed only after provider completion. Shared command owners must retain the observed cancellation reason separately from physical failures and cleanup ownership. Carry that fact through failure wrapping so adapters can preserve the exact reason without interpreting it. Client cancellation alone does not prove native work stopped. For atomic publication, document the cancellation cutoff and preserve any committed output's publication receipt. Queued and retried work must retain the complete accepted execution controls, including non-default lifecycle deadlines and cancellation signals.
• Release only owned resources. Attaching owns a connection or session unless the provider contract explicitly establishes target ownership. A helper exit, missing reply, or missing PID does not establish target exit.
• Retain successful child cleanup and retry only unresolved children, including when close options change. Preserve observed child failure or activity when another child's health is unavailable; idle plus missing coverage stays unknown. Bind cleanup failures to their exact resource owner. Resolve current cleanup uncertainty only after that owner confirms release, while preserving the original failure and completed observations. Later failure composition must report only resources whose cleanup remains unresolved. Carry cleanup capabilities explicitly in typed outcomes so consumers can bind returned errors to exact owners without reparsing diagnostic cause chains. Bind every caller-visible retry error and aggregate, including an error already produced by the provider. An aggregate remains incomplete until all owners it reports are released; releasing one child cannot clear another child's status.
• Await one-shot cleanup without discarding the completed result or primary diagnostic. Preserve partial observations, remaining resources, and the cleanup owner's recovery instructions. CLI adapters should reuse finishAnalysisCommand where its contract applies rather than duplicate close/finally handling.
• Give descriptor-backed reads an owner before opening the file. A rejected close must retain the exact handle and preserve any earlier failure. If an abortable caller stops waiting, keep the underlying work in that owner's lifetime so shutdown cannot report release before finalization settles. Admit the entire inspection once, including later reads and finalization. Helpers must borrow that admission or use an operation child scope; re-entering the same draining scope can make cleanup wait for its own caller. Retry retained cleanup before admitting new work and keep admission blocked while it remains unresolved. Link the originating cleanup error to its exact owner so confirmed release resolves its cleanup marker while preserving the earlier diagnostic. Shared CLI/MCP adapters cannot infer that confirmation.
• Provider profile selection owns every asynchronous candidate through its terminal result and finalization. The registry owns profile-file cleanup, joins all automatic-selection children, and closes those file owners before reporting candidate shutdown. Final caller cancellation joins the selection; an adapter that ignores cancellation remains active and owned until it settles. Block new admission during shutdown and while cleanup remains unresolved; reopen after confirmed retry. Preserve failed results before considering a later signal, and retain every child's attributed cleanup in mixed outcomes.
• Release child descriptors before removing their containing root. Retain a composite owner when either stage fails so retry preserves that ordering. A Windows command leader's exit does not establish Job Object closure. Keep the process-tree observer and command lock alive through failed cleanup retries until the owned tree's close event.

Exercise the applicable lifecycle regression scenarios through the producing owner and affected CLI/MCP consumers.

Implement and evaluate

Put provider protocols/parsing in adapters and shared CLI/MCP workflows in the application layer. Share Evidence provenance, unknown projection, and session retention semantics; matching payloads alone do not establish parity.

Measure the resource before choosing a budget and enforce it before the costly step. Account for value alternatives, trace-frame products, retained records, serialization expansion, and temporary-file growth separately. Derive facet completeness from examined records and exhaustiveness, rather than diagnostic prose or an empty failure list. Preserve observations independently of cleanup success.

Update canonical contracts, output schemas, examples, generated artifacts, and relevant docs together. Verify converted advertised schemas and success, malformed, unavailable, cancellation, and partial outcomes through affected consumers. Real-engine claims require the matching provider lane; see testing.md.

For fixed tuples in public contracts, use src/domain/fixedTupleSchema.ts: Zod's tuple projection omits implicit length bounds and Draft 2020-12 items, which some clients require even alongside prefixItems. Tuples with a rest schema also need explicit minimum lengths. Check parser/schema parity for empty, short, overlong, and malformed values in both input and output projections.

When discoverability changes, evaluate representative broad, direct, and negative tasks on the intended host. Record host/model/catalog, selected tools, arguments, errors, retries, and task outcomes. Schema validity and keyword heuristics do not establish successful tool selection. See mcp-contracts.md for shipped runtime behavior.