Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
docs: add REA tool design guidance (#485)
morluto36aeec95863c
diff --git a/AGENTS.md b/AGENTS.mdindex c97ef9cfe..96752fa9e 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -17,129 +17,54 @@ REA is a local-only tool; do not sanitize actionable local diagnostics such as a## Project Structure & Module Organization-REA is a layered ESM TypeScript application. Dependencies flow inward: `domain` underlies `contracts` and the shared `process` primitives; providers depend on those layers, followed by `application`, `server`, and the entry adapters.--See [docs/architecture.mermaid](docs/architecture.mermaid) for a visual architecture diagram.--- `scripts/rea.mjs`: executable dispatcher. Routes only bare `mcp` and `--mcp` to the production stdio server; Incur handles registration utilities and one-shot commands.-- `src/main.ts`: MCP adapter. Parses config, wires the shared session runtime, starts stdio transport, and owns process-lifetime shutdown.-- `src/cli.ts`: one-shot CLI adapter for setup, diagnostics, analysis, and decompilation.-- `src/config.ts`: Zod-validated parsing of environment configuration into `AppConfig`.-- `src/domain/`: pure, side-effect-free modules. `errors.ts` owns the tagged error algebra; `result.ts` owns `Result`/`ok`/`err`; `hopperValues.ts` owns shared function-dossier values plus Hopper boundary parsers; `symbolAnalysis.ts` parses Swift/ObjC names; `javascriptApplicationGraph.ts` validates and canonically commits the provider-neutral JavaScript Application Graph; `javascriptStaticAnalysis.ts` performs bounded AST-only JavaScript structure recovery.-- `src/contracts/`: caller-visible tool schemas and catalog metadata; `toolContracts.ts` owns the canonical inventory and `enhancedInputs.ts` owns enhanced input parsing.-- `src/process/`: provider-neutral process ownership and lifecycle primitives. It owns private runtime roots, session-assigned run identity and token-verified lineage, absolute startup deadlines, correlated request waits, bounded output capture, and TERM-to-KILL cleanup without defining any provider wire protocol.-- `src/replay/`: Linux x64 controlled-JavaScript-replay adapter. It owns exact runtime closure inspection, Bubblewrap/seccomp/cgroup admission, the disposable worker, strict parent/worker protocol validation, and complete cleanup observation.-- `src/browser/`: loopback CDP/Inspector discovery, bounded WebSocket transport, exact-origin or canonical-root target authorization, passive browser/Electron and attach-only Node/Electron V8 observation, plus controlled Playwright scenarios with explicit launch/attach ownership and cleanup.-- `src/hopper/`: Hopper launch and Unix-socket protocol mechanics. `BridgeLauncher.ts` spawns the Hopper app with the in-process bridge, `HopperClient.ts` correlates request/response over the socket with timeouts and cancellation, `protocol.ts` frames bridge messages.-- `bridge/hopper_bridge.py`: runs inside Hopper and adapts declared operations to Hopper's public Python API. Hopper's bundled MCP server is not used.-- `src/ghidra/`: exact Ghidra 12.1.2/JDK 21 inspection, analysis-profile commitment, digest-bound target snapshots, isolated `analyzeHeadless` launch, authenticated Unix-socket or Windows loopback transport, bounded serial request queue, and strict inventory/function boundaries.-- `src/dotnet/`: execution-free managed PE/CLI inspection. It owns bounded PE, CLI metadata, heap, table, and resource parsing for `rea-dotnet-static`; it must never load, reflect, execute, decompile, or resolve target assemblies.-- `bridge/ghidra/ReaGhidraBridge.java`: packaged read-only `HeadlessScript` loaded through Ghidra's `scriptPath`; it owns the persistent decompiler and adapts admitted inventory, function, reference, and CFG operations to public Ghidra APIs.-- `src/application/`: shared CLI/MCP session composition, setup and diagnostics, and enhanced workflows. `AnalysisProviderRegistry` discovers overlapping deep candidates without starting them; `SessionProviderRouter` binds one candidate per target and composes it with disjoint auxiliary providers; `JavaScriptArtifactReconstruction.ts` safely projects local directories/ASARs and inert bundle syntax into the application graph without adding a caller-visible tool yet.-- `src/server/`: MCP request translation. `createServer.ts` assembles the MCP server, `registerOfficialTools.ts`/`registerEnhancedTools.ts` register each tool set, `toolResult.ts` maps `Result` values to MCP content.-- `docs/product-catalog.json`: generated package, tool-family, provider, setup-client, and CLI facts. Regenerate it from source; do not edit it by hand.-- `tests/`: Vitest suite. Focused immutable domain builders live beside their production owner as `src/domain/*.fixture.ts`; `tests/fixtures/` holds reusable provider-process fixtures, source-owned Electron/Webpack/Rspack artifact trees, and the fake launcher, Hopper bridge, and CDP seams.-- `scripts/verify-real-hopper.mjs`: real-Hopper end-to-end verifier.-- `scripts/verify-real-ghidra.mjs`: real Linux Ghidra verifier for x86-64 debug/stripped ELF, AArch64 ELF, PE, and Mach-O function semantics plus complete cleanup.-- `scripts/verify-real-ghidra-windows.mjs`: real Windows x64 Ghidra P0 verifier for the source-owned native PE fixture, all 19 admitted operations, digest linkage, loopback transport, and cleanup.-- `scripts/verify-real-browser.mjs`: real Chrome end-to-end verifier for the passive CDP provider.-- `scripts/print-mcp-config.mjs`: prints an MCP server config with absolute paths filled in (`npm run config:print -- /path/to/binary`).+REA is a layered ESM TypeScript application. Dependencies flow inward from pure domain logic through contracts, providers, application workflows, and CLI/MCP adapters. See [docs/architecture.mermaid](docs/architecture.mermaid) for the component map.++- `src/domain/` owns pure provider-neutral semantics; `src/contracts/` owns caller-visible schemas and the canonical tool inventory.+- `src/hopper/`, `src/ghidra/`, `src/browser/`, `src/replay/`, `src/native/`, `src/artifacts/`, and `src/dotnet/` own provider-specific boundaries. Keep provider protocols out of domain and application code.+- `src/application/` composes shared CLI/MCP workflows; `src/server/` translates MCP requests; `src/cli.ts` and `src/main.ts` are the CLI and MCP entry points.+- `src/process/` owns shared process lifecycle primitives, not provider wire protocols. `bridge/` contains provider-side adapters.+- `tests/` contains unit, composition, boundary, acceptance, and conformance tests. `scripts/verify-*` contains real-toolchain checks.+- `docs/product-catalog.json` is generated. Update its source contracts and regenerate it; do not edit it directly.## Build, Test, and Development Commands-- `npm ci`: install exact lockfile dependencies.-- `npm run deps:check`: verify that installed direct dependency versions match the root lockfile; on failure, run `npm ci`, then retry.-- `npm run metadata:generate`: refresh checked-in package metadata after package, lockfile, or skill-version changes.-- `npm run metadata:check`: verify checked-in package metadata without rewriting it.-- `npm run build`: compile `src/` into `dist/`.-- `npm run build:cached`: compile through Turbo and reuse a valid local build cache entry.-- `npm test`: restore or build `dist/`, then run the Vitest suite once without coverage or retries locally.-- `npm run test:local`: run only changed and related tests without rebuilding `dist/`; use this for the lightweight local loop.-- `npm run test:fast`: run pure and subprocess test projects without the serial integration group.-- `npm run test:changed`: run changed and related non-serial tests once.-- `npm run test:integration`: run the serial filesystem, process, and CLI integration group.-- `npm run test:watch`: watch changed and related non-serial tests, without coverage.-- `npm run test:coverage`: run the complete suite with coverage; CI shards the suite and owns JUnit reporting.-- `npm run typecheck`: run strict TypeScript checks without emitting files.-- `npm run lint`: apply oxlint rules (complexity, max-lines, unused vars, and TypeScript-specific checks).-- `npm run lint:fix`: auto-fix oxlint violations where possible.-- `npm run format:check`: verify Prettier formatting.-- `npm run check`: run cached typecheck, lint, format:check, knip, and package-metadata freshness tasks.-- `npm run check:fast`: run only cached typecheck and lint for rapid local and pre-push feedback.-- `npm run check:ci`: run the static gate plus duplicate-code and debt-marker scans.-- `npm run check:test`: run the cached static tasks plus the uncached complete test suite.-- `npm run check:pr`: run the test gate plus uncached generated-document validation for PR preparation.-- `npm run knip`: detect unused files, dependencies, and exports.-- `npm run jscpd`: detect duplicate code blocks.-- `npm run scan:todos`: scan for TODO, FIXME, and HACK markers.-- `npm run verify:hopper`: build and run the real-Hopper verifier with two distinct binaries.-- `npm run verify:ghidra`: build and run the real-Ghidra verifier against `GHIDRA_INSTALL_DIR` and optional `GHIDRA_TARGET_PATH`.-- `npm run verify:ghidra:windows`: build and run the real Windows Ghidra verifier against `GHIDRA_INSTALL_DIR` and the source-owned x64 PE fixture.-- `npm run verify:browser`: build and run the real Chrome verifier against `REA_BROWSER_EXECUTABLE` or a platform-default Chrome-family executable, including browser-scenario CLI parity, attach disconnect-only ownership, launched-process termination, and temporary-profile cleanup.-- `npm run verify:inspector`: build and run the real attach-only Node Inspector verifier through the public CLI.-- `npm run verify:managed`: build and run the source-owned managed PE/CLI conformance verifier for artifact triage, member inspection, managed/native boundary declarations, token drift comparison, malformed metadata, non-managed degradation, managed application-graph projection, manifest-verifier self-test, and optional BYO ILSpy oracle checks; set `REA_MANAGED_APP_MANIFEST_PATH` to verify an operator-local managed app manifest, including optional graph/trace assertions, and set `REA_ILSPY_CMD_PATH` to an absolute `ilspycmd` path to run the real ILSpy reconstruction oracle.-- `npm run evidence:generate`: regenerate the managed conformance manifest and evidence completion ledger from live verifier output.-- `npm run evidence:check`: rerun managed conformance and fail on generated manifest, completion ledger, or bundled skill drift.-- `npm run verify:replay`: build and run the real Linux Bubblewrap/seccomp/cgroup verifier against source-owned replay fixtures; set `REA_REPLAY_INPUT_PATH` to verify an operator-local manifest.-- `npm run verify:package`: pack and test the CLI, setup transaction, skill, and canonical target-free MCP catalog in an isolated environment.-- `npm run docs:api`: render uncommitted API documentation from JSDoc comments into `build/api-docs/` using TypeDoc.-- `npm run docs:api:cached`: render API documentation through Turbo or restore a valid local result.-- `npm run docs:generate`: refresh committed metadata and render the uncommitted API documentation.-- `npm run docs:check`: verify generated package metadata, the canonical product catalog, caller-visible documentation facts, TypeDoc rendering, and the error JSON schema.--Local full-suite Vitest runs use one worker and serial project groups because-boundary tests own subprocess fixtures. CI retains the existing two-worker-budget. The `test`, `docs:check`, and `docs:generate` commands use-repository-local locks and refuse overlapping runs; interrupted commands can-leave a stale lock that is removed automatically when its owner PID is no-longer alive. The `npm test` build runs inside that lock.--- `npm run config:print -- /path/to/binary`: print an MCP server config with absolute paths.-- `HOPPER_TARGET_PATH=/path/to/binary npm start`: launch Hopper and run the built stdio MCP server.--Pre-commit hooks via Husky format then lint staged source files. Pre-push runs `npm run check:fast`; CI owns the broader static and generated-document gates. Use `npm run lint:fix` to auto-correct violations locally.+- `npm ci`: install the locked dependencies.+- `npm run build:cached`: build the CLI and MCP server.+- `npm run test:local`: run focused tests for changed code.+- `npm run check:fast`: run cached typecheck and lint checks.+- `npm run check:pr`: run the deterministic PR gate and generated-document checks.+- For provider-dependent changes, see [docs/testing.md](docs/testing.md) and run the matching real-provider verification.++See [docs/testing.md](docs/testing.md) for test scopes and verification lanes and [CONTRIBUTING.md](CONTRIBUTING.md) for contribution checks. Pre-commit formats and lints staged source; pre-push runs `npm run check:fast`.## Configuration & Environment Variables-- `REA_ANALYSIS_PROVIDER` (optional, default `auto`): require one deep-analysis provider ID for startup and one-shot commands, or use deterministic automatic selection. A request-level `provider_id`/`--provider` takes precedence.-- `GHIDRA_INSTALL_DIR` (optional): absolute root of an extracted official Ghidra 12.1.2 distribution. The adapter supports Linux x64 and the experimental Windows x64 P0 boundary documented in `docs/windows-ghidra-p0.md`.-- `JAVA_HOME` (optional): absolute 64-bit full JDK 21 root used by Ghidra. When absent, doctor probes `java`/`javac` from `PATH`.-- `REA_ILSPY_CMD_PATH` (optional): absolute path to a bring-your-own `ilspycmd`; doctor reports its configured version, and `verify:managed` can use it as a real reconstruction oracle without making ILSpy a setup-installed dependency or canonical parser.-- `HOPPER_TARGET_PATH` (optional): absolute initial binary or `.hop` target. Target-free MCP sessions use `open_binary` instead.-- `HOPPER_LAUNCHER_PATH` (optional): override the Hopper executable path (defaults to `/Applications/Hopper Disassembler.app/Contents/MacOS/hopper`).-- `HOPPER_TARGET_KIND` (optional, default `executable`): startup kind for `HOPPER_TARGET_PATH`; dynamic targets are classified from their paths and headers.-- `HOPPER_LOADER_ARGS_JSON` (optional): JSON array overriding derived Hopper loader arguments for supported executable targets, e.g. `["-l","Mach-O","--aarch64"]`.-- `REA_BROWSER_OBSERVE_ENABLED` (optional, default `false`): add browser observation authority to the administrator ceiling.-- `REA_BROWSER_CDP_ENDPOINTS_JSON` (optional): approved literal loopback CDP HTTP endpoints.-- `REA_BROWSER_ALLOWED_ORIGINS_JSON` (optional): exact HTTP(S) page origins approved for passive observation.-- `REA_BROWSER_SCENARIO_ENABLED` (optional, default `false`): add controlled browser automation to the administrator ceiling.-- `REA_BROWSER_SCENARIO_AUTO_GRANT` (optional, default `false`): issue the exact configured browser-automation ceiling as an administrator grant for trusted unattended use.-- `REA_BROWSER_SCENARIO_EXECUTABLE_ROOTS_JSON` (optional): canonical executable roots approved for provider-owned browser launch.-- `REA_BROWSER_SCENARIO_CDP_ENDPOINTS_JSON` (optional): literal-loopback CDP endpoints approved for external-browser attachment.-- `REA_BROWSER_SCENARIO_ALLOWED_ORIGINS_JSON` (optional): exact HTTP(S) page origins approved for browser scenarios.-- `REA_BROWSER_SCENARIO_ALLOWED_ENV_JSON` (optional): environment-variable names that scenario secret references may resolve.-- `REA_ELECTRON_OBSERVE_ENABLED` (optional, default `false`): add passive Electron file-page observation authority to the administrator ceiling.-- `REA_ELECTRON_CDP_ENDPOINTS_JSON` (optional): approved literal loopback Electron CDP HTTP endpoints.-- `REA_ELECTRON_FILE_ROOTS_JSON` (optional): canonical filesystem roots approved for passive Electron page observation.-- `REA_V8_INSPECTOR_OBSERVE_ENABLED` (optional, default `false`): add passive attach-only Node/Electron Inspector observation authority to the administrator ceiling.-- `REA_V8_INSPECTOR_ENDPOINTS_JSON` (optional): approved literal-loopback Node/Electron Inspector HTTP endpoints.-- `REA_V8_INSPECTOR_FILE_ROOTS_JSON` (optional): canonical filesystem roots approved for Inspector targets and script locations.-- `REA_V8_INSPECTOR_ALLOWED_ORIGINS_JSON` (optional): exact HTTP(S) origins approved for Electron renderer Inspector targets and scripts.-- `REA_JAVASCRIPT_REPLAY_ENABLED` (optional, default `false`): add controlled extracted-module execution authority to the administrator ceiling.-- `REA_JAVASCRIPT_REPLAY_ROOTS_JSON` (optional): exact canonical source roots approved for controlled replay.-- `REA_JAVASCRIPT_REPLAY_NODE_PATH`, `REA_JAVASCRIPT_REPLAY_BWRAP_PATH`, `REA_JAVASCRIPT_REPLAY_SYSTEMD_RUN_PATH`, `REA_JAVASCRIPT_REPLAY_SYSTEMCTL_PATH`, and `REA_JAVASCRIPT_REPLAY_SHELL_PATH` (optional): absolute paths committed by each replay plan; defaults target the current Node runtime and standard Linux system executables.+Configuration is parsed and validated by `src/config.ts` and `src/config/`. Keep user-facing setup and provider configuration in [README.md](README.md) and the relevant guide under `docs/`; do not maintain a second environment-variable catalogue here.## Coding Style & Naming ConventionsUse ESM TypeScript, two-space indentation, and Prettier defaults. Keep compiler strictness intact (`strict`, `exactOptionalPropertyTypes`, `noUncheckedIndexedAccess`, `verbatimModuleSyntax`). Use `camelCase` for values/functions, `PascalCase` for classes/types, and `UPPER_SNAKE_CASE` for constants. Parse unknown values at every MCP, environment, and subprocess boundary. Avoid `any`, unchecked casts, non-null assertions, import-time I/O, and floating promises. Exported APIs require concise JSDoc. Model expected failures with the tagged error algebra and `Result`, not broad exception wrappers.+## Designing MCP Tools++Start from the analyst question and desired result, not a provider API. Before adding a tool, inspect the existing contract and its nearest alternative.++- Use bounded **inspect/search** tools for facts about a target or candidate set; use **trace** tools for relationships; use **compare** tools for explicitly paired inputs.+- Add a **workflow** when agents repeatedly orchestrate the same calls. Compose inside REA and return joined evidence instead of making callers loop.+- Use **observe/capture/replay** only when runtime activity is required, and declare authority and lifecycle effects in the contract.+- Extend an existing tool when intent and result contract are unchanged. Add a tool for a distinct analyst outcome or materially different authority.+- Keep caller-facing names and results provider-neutral. Put engine-specific behavior in provider adapters and report each provider's exact coverage.+- Bound work, make truncation and unsupported facets explicit, and keep observed, derived, inferred, and unknown results distinct.+- Include artifact identity, source locations, Evidence links, actionable errors, and limits when they affect conclusions.+- Implement shared application workflows behind CLI and MCP adapters. Update canonical contracts and generated catalog together.++See [docs/tool-design.md](docs/tool-design.md) for the design checklist. When usability or tool selection changes, evaluate representative CLI/MCP tasks as well as schema and transport behavior.+## Testing GuidelinesName tests `*.test.ts`. Use Vitest and production seams (`tests/fixtures/`) rather than module mocks. Domain tests assert pure behavior; adapter tests use fake launcher/socket seams; MCP tests connect with the client SDK version pinned in `package.json`. Preserve the canonical tool inventory defined by `TOOL_CONTRACTS` and verified through `CATALOG_IDENTITY` and generated product metadata. Cover malformed input, cancellation, timeouts, process exit, concurrency, limits, and clean shutdown. Real Hopper, Ghidra, browser, JavaScript replay, managed conformance, and any real managed-tool claims cannot be replaced by mocks; use the corresponding `verify:*` command.-MCP tools are agent-computer interfaces. Optimize them first for successful agent use: distinct purposes, clear names and parameters, relevant result context, actionable errors, and realistic multi-step workflows. Validate tool-design changes with representative agent tasks and transcripts when possible; schema validity and transport success alone do not prove that a tool is easy for an agent to use.--MCP tool catalogs must remain complete and self-describing. Prefer capability- and session-scoped tool advertisement over schema truncation. Never use serialized byte counts as a proxy for model-context cost, token use, tool usability, or agent performance. Measure bytes only when evaluating a named transport, storage, or protocol constraint. Any model-context or token-efficiency claim must identify the client and its actual model-facing projection and tokenizer, since clients may omit, transform, dereference, or otherwise reproject MCP schemas. Do not weaken names, descriptions, schemas, examples, errors, or result context to improve a byte-based metric.+Keep tool catalogs complete and self-describing; prefer capability- and session-scoped availability over schema truncation. Serialized bytes alone do not measure agent usability or model context cost.## Commit & Pull Request Guidelinesdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 1a5bcbd45..19dfcaa5f 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -2,6 +2,8 @@REA welcomes focused bug fixes, documentation improvements, tests, and reverse-engineering workflow enhancements. Open an issue before a large contract or architecture change so its scope can be agreed before implementation.+When adding or changing an MCP tool, follow the [tool design guide](docs/tool-design.md) and preserve the canonical contracts and generated catalog.+## Development setupREA development requires Node.js 24.18.x and npm 11.16.x. Real-Hopper verification additionally requires either macOS 12+ or an officially supported Linux host (Ubuntu 24.04+, Fedora 41+, or 64-bit Arch) and an installed Hopper application. Linux demo verification uses its own private Xvfb display and does not require a desktop session. Run `nvm use` before installing dependencies.diff --git a/docs/tool-design.md b/docs/tool-design.mdnew file mode 100644index 000000000..2110782b4--- /dev/null+++ b/docs/tool-design.md@@ -0,0 +1,70 @@+# 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](mcp-contracts.md) for shipped runtime behavior and+[testing.md](testing.md) for test boundaries and verification lanes.