RFC-0002: Agent-ergonomic MCP service contract

[tlrmchlsmth]

Summary

• define a cross-cutting agent-ergonomic contract for every MCP service in nm-hard-tools
• allow domain-appropriate surfaces: a single bounded direct-action tool, a lifecycle family, or another coherent goal-oriented interface
• treat YAML and other configuration documents as valid primary inputs when an extensible authoritative schema cannot be represented faithfully by a reduced JSON model
• define conditional contracts for discovery, planning, asynchronous status, listings, cancellation, artifacts, semantic inspection, structured queries, and comparison
• require bounded results, concise text, actionable errors, truthful metadata, authorization safety, compatibility, and capability-selected conformance tests

Status

RFC-0002 remains in draft/spec for discussion. This PR does not implement or finalize the contract.

Relationship to domain RFCs

RFC-0002 governs all MCP tooling in this repository. Domain RFCs retain authority over concrete service goals, exact tool names and cardinality, payload and result schemas, operational semantics, and domain error codes. A domain RFC may strengthen the umbrella contract but may not silently weaken an applicable requirement.

This makes RFC-0001's model-deployment design a supported profile rather than an exception:

• its single deploy_model direct-action tool is permitted
• its bounded YAML manifesto_config remains the primary interface
• YAML safety limits, pinned schema/renderer authority, validation-before-mutation, redaction, and separate exact-byte digest versus semantic deployment identity satisfy the configuration-document model
• formatting-equivalent documents converge only while the schema and domain-declared operator identity context are held constant

RFC-0002 does not require a lossy structured replacement for a configuration language that can express more than a fixed JSON input model.

Revised implementation gap analysis

The earlier audit treated evaluation and benchmark lifecycle shapes as universal. The draft now makes those requirements conditional on the capabilities a service actually exposes.

Priority	Cross-cutting change
P0	Make every top-level tool input a closed JSON object, including tools whose primary domain payload is a bounded YAML or other configuration-document string.
P0	Ensure every tool advertises a stable title, selection-oriented description, truthful annotations, and an output schema covering every structured success and tool-error variant it can return.
P0	For configuration-document inputs, advertise format, byte and document limits, schema authority or pinned consumer, and handling of aliases, duplicate keys, tags, inheritance, and unknown fields; validate safely before mutation.
P0	For tools claiming idempotent convergence, define semantic input and operator-controlled identity context, and reconcile equivalent concurrent or repeated calls to one logical outcome. A separate plan tool is required only when the domain chooses a split planning/execution workflow.
P0	Return recognized domain failures as tool errors with stable code, concise message, and retryability when structured; keep protocol failures at the protocol layer and validate every advertised error schema.
P1	Stop repeating complete structured results in text; return a concise summary and disclose truncation, sampling, approximation, staleness, or omitted evidence.
P1	Add deterministic resumable pagination only to listings, inspections, queries, or comparisons that can exceed one bounded response.
P1	When complex results warrant inspection, provide discoverable semantic views and bounded provenance-bearing access. Artifact queries and cross-result comparison are optional capabilities, but their contracts apply when exposed.
P1	Prefer useful bounded summaries, narrower follow-up actions, pagination, or artifact references over oversize-only failures when such a representation is available.
P2	Replace pre-RFC surface tests with capability-selected agent-journey conformance tests: all services cover self-description, valid invocation, unknown input rejection, metadata, result bounds, domain failure, authorization, and schema conformance; lifecycle, configuration-document, listing, inspection, and comparison tests apply only where advertised.

Current alignment

• Stateless MCP 2026-07-28 transport and discovery.
• Server identity, cache hints, deterministic tool ordering, and origin checks.
• Strict evaluation inputs and operator-controlled targets/profiles.
• Evaluation submission and cancellation are already largely idempotent.
• Authentication occurs before MCP parsing when configured.
• RFC-0001's bounded YAML deployment contract is compatible with the generalized RFC-0002 model.

Validation

• govctl check passes; remaining diagnostics are expected draft since warnings and the pre-existing ADR reference warning
• independent RFC review completed; its authority, identity-context, discovery, planning, and conformance findings are incorporated
• git diff --check passes