88 lines
5.1 KiB
Markdown
88 lines
5.1 KiB
Markdown
# 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](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](mcp-contracts.md) for
|
|
shipped runtime behavior.
|