Operator Note: API + MCP Contracts That Prevent Brittle Agent Behavior

Operator memo: Stable agent behavior comes from contracts, not prompt cleverness.

Problem

Agents become brittle when interfaces are underspecified: ambiguous fields, hidden side effects, and inconsistent error semantics.

Contract stack

User intent -> Planner -> MCP discovery
                        |
                        v
                API contract resolver
               /          |           \
          Schema       Policy       Idempotency
          checks       checks         token
               \          |           /
                  Execution + typed errors
                           |
                           v
                     Observability

Checklist we use

Contract area	Minimum standard	Failure prevented
Schema determinism	Strict required fields, enums, canonical units	Ambiguous actions
Error semantics	Retryable vs terminal error codes	Infinite retry loops
Idempotency	Replay-safe state mutation endpoints	Duplicate writes
MCP capability docs	Constraints, examples, and side effects explicit	Wrong tool assumptions

KPI snapshot

Metric	Target	Interpretation
Schema validation pass rate	> 98%	Input contracts are understood by agents
Retry loop escape rate	100%	Error taxonomy is actionable
Duplicate mutation incidents	0	Idempotency is enforced

Implementation notes

Trade-off: rigid contracts slow ad-hoc integrations but protect production reliability.
Constraint: versioning discipline is required when multiple agent flows share the same tools.
Operational rule: new MCP tools ship with examples and failure-mode tests before exposure.

Outcome

Better contracts reduce hallucinated actions, improve retry reliability, and make multi-agent orchestration substantially more predictable.