mirror of
https://github.com/morluto/rea.git
synced 2026-11-04 22:06:10 +00:00
78 lines
5.5 KiB
Markdown
78 lines
5.5 KiB
Markdown
# 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](mcp-contracts.md) for shipped runtime behavior and
|
|
[testing.md](testing.md) for test boundaries and verification lanes.
|