5.1 KiB
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 complete evidence inline, with artifact/provider identity, source locations, Evidence references, and relevant confidence and limitations. 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.
- 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.
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.
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.