reverse-engineering-anything/docs/tool-design.md

MCP tool design

Design tools around analyst tasks. A provider API is an implementation detail; expose it directly only when users need a bounded, reusable primitive that cannot be expressed through an existing contract.

Choose the tool shape

Shape	Use it for	Contract should return
inspect	Facts about one explicit target, address, object, or resource	Bounded fields, source locations, and facet-level availability
search / list	Finding candidate targets or entities	Stable ordering, filters, pagination, and exact totals or an explicit unknown
trace	Relationships across code, metadata, UI resources, or observations	Typed edges, evidence per edge, traversal limits, and unresolved paths
compare	Two explicitly identified artifacts, versions, or evidence sets	Paired identity, comparable coverage, and deltas with evidence
workflow	A repeated analyst question that otherwise requires a fragile call sequence	The composed result, contributing evidence, and partial/unavailable facets
observe / capture / replay	A question that requires runtime behavior	Required authority, launch/attach behavior, bounds, 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 bounded batch when agents repeat scalar calls over a coherent set. Add a workflow when agents repeatedly compose the same stages. Add a new 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 instructional. A prompt can suggest a sequence, but it does not replace a tool that must perform bounded work or return durable evidence.

Avoid scalar-tool sprawl, model-authored N+1 loops, opaque mode flags, and mega-tools that combine unrelated discovery, execution, and mutation.

Define the contract

• Use strict object inputs with explicit required fields, enums, and bounds.
• Make pagination, truncation, partial failure, cancellation, and expected unavailable states explicit. Missing evidence is unknown, not empty or false.
• Return task-oriented results with artifact identity, provider/version, addresses or resource paths, Evidence IDs, confidence, and limitations when they affect the conclusion.
• 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.