rea/docs/tool-design.md

MCP tool design

Design tools around analyst tasks. A provider API is an implementation detail; expose it directly when it gives agents a useful, reusable capability that cannot be expressed through an existing contract. Do not impose caller-facing limits merely to make work fit an assumed agent budget. Keep real input-format, protocol, authority, and resource-safety constraints, and report their effects.

Choose the tool shape

Shape	Use it for	Contract should return
inspect	Facts about one explicit target, address, object, or resource	Relevant fields, source locations, and facet-level availability
search / list	Finding candidate targets or entities	Stable ordering and useful result context; expose pagination when the result format or caller's query needs it
trace	Relationships across code, metadata, UI resources, or observations	Typed edges, supporting evidence, and unresolved paths; identify any genuine traversal boundary
compare	Two explicitly identified artifacts, versions, or evidence sets	Paired identity, comparable coverage, and deltas with evidence
workflow	A distinct analyst outcome that benefits from composition inside REA	A useful inline result, contributing evidence, and partial/unavailable facets
observe / capture / replay	A question that requires runtime behavior	Required authority, launch/attach behavior, real operational constraints, lifecycle, and cleanup status

These are task shapes, not required prefixes. Name a tool for the action and object agents reason about; keep the name distinct from nearby alternatives.

Decide whether to add a tool

1. State the user intent and the smallest result that answers it.
2. Inspect the canonical tool contracts, current provider capabilities, and representative CLI/MCP traces. Record the nearest competing tool.
3. Extend an existing contract when the intent and result are the same. Add a batch or composed workflow when it materially improves a demonstrated task; do not force agents through extra calls or collapse distinct tasks into one tool. Add a tool when it answers a distinct analyst question or has a materially different authority or result contract.
4. Keep public tool names and result semantics provider-neutral. Put engine- specific parsing and protocol handling in adapters. Advertise exact support per provider; do not create parallel tools just because engines differ.
5. Keep prompts optional and concise. They may point out useful tools, but must not prescribe a call sequence when the task can be answered directly.

Avoid opaque mode flags and mega-tools that combine unrelated discovery, execution, and mutation. Prefer a useful direct tool call over a tool sequence or model-authored loop when one call can answer the question.

Define the contract

• Use strict object inputs with explicit required fields and enums. Add numeric bounds only when the format, protocol, authority, or a measured resource constraint requires them.
• Return complete results by default. Make real pagination, truncation, partial failure, cancellation, and unavailable states explicit. Missing evidence is unknown, not empty or false.
• Return task-oriented results inline with artifact identity, provider/version, addresses or resource paths, Evidence references, confidence, and relevant limitations. Do not require agents to fetch a resource or dereference an opaque Evidence link to understand a tool result.
• Separate observed facts from derived and inferred edges. Cite the evidence supporting every important relationship; preserve unresolved edges.
• Declare read-only, mutation, process, filesystem, network, and UI effects truthfully in the contract and permission boundary.
• Keep provider-specific types out of provider-neutral domain and application layers. Normalize supported provider results without implying equal coverage.

Implement and evaluate

• Put shared user workflows in the application layer; keep MCP translation in the server adapter and CLI behavior aligned with the same workflow.
• Update the canonical contract inventory, output schemas, examples, generated catalog, and relevant docs together.
• Verify valid, malformed, boundary, unavailable, cancellation, and partial results at the owning boundaries. Use real-provider checks for claims that depend on external analysis engines.
• Evaluate representative broad and direct task prompts on the intended MCP host when tool selection is the question. Record the host, model-facing tool catalog, selected tool, arguments, errors, retries, and task outcome. Schema validity or word-overlap heuristics do not prove discoverability.

See mcp-contracts.md for shipped runtime behavior and testing.md for test boundaries and verification lanes.