API-first and ANCC share DNA. Both say: define the contract before writing code. Both reject "build it, then figure out the interface." Both gate on compliance. Both treat the spec as the source of truth.
But they solve different problems for different consumers.
# API-first
POST /deploy → 200 OK
# Developer reads docs, handles edge cases, writes retry logic
# ANCC
deploy doctor --format json → {"status": "degraded", "checks": [...]}
# SKILL.md declares:
# does not delete infrastructure
# requires approval for irreversible actions
# hands off to rollback tool on failure
# Agent reads contract, acts, no guessingThe difference is not REST vs CLI, not OpenAPI vs SKILL.md. That is surface.
The real difference is: who is trusted to fill in the gaps.
Humans infer all of this from docs, context, tribal knowledge, and experience. Agents cannot.
ANCC is API-first plus the pieces that agents need to operate without supervision. Without these constraints, agent systems do not degrade gracefully — they fail catastrophically. Six constraints that API-first does not have:
"What this does NOT do" is a required section. It defines permanent boundaries — what the tool must never become.
This is the immune system. API-first has nothing like it. APIs grow into blobs because nothing structural prevents it. In an agent-operated system, unbounded growth is not technical debt — it is a safety failure.
"I stop here. Hand to X." Explicit declarations of where a tool's responsibility ends and what kind of tool takes over.
This is composition without guessing. In API-first, composition is human wiring — a developer reads the docs, understands intent, writes glue code. In ANCC, agents read the handoff contract and route autonomously.
tool doctor --format json reports runtime truth: what is working, what is degraded, what is unavailable.
API-first equivalent: "it compiled, good luck." A health endpoint that returns {"status": "ok"} tells an agent nothing about whether the tool can actually do its job right now.
Exit codes with defined semantics. Structured JSON with provenance classification. Every output field tagged as observed, declared, inferred, or unknown.
API-first equivalent: HTTP status codes and vibes. A 200 with a JSON body tells you the shape. It does not tell you whether the data is live, cached, or six months stale. Agents acting on stale data as if it were live truth cause stupid decisions at industrial scale.
The extend-vs-new rubric. Five questions that determine whether a change belongs in the existing tool or requires a new one. Scope pressure detection at 10+ commands. Kill paths for tools that should not exist.
API-first equivalent: version everything forever. v1, v2, v3 — each version accumulates features, none are removed, and the API surface only grows. In an agent-operated system, this is not versioning — it is system cancer.
What happens when an agent cannot decide? The extend-vs-new rubric scores 2-3 out of 5. Constraints conflict. The right action is genuinely unclear.
API-first answer: the developer figures it out. There is no mechanism for this because there does not need to be — humans resolve ambiguity naturally.
ANCC answer: the agent must not guess. The decision escalates through a defined chain — try locally, apply conservative default, submit to a structured reasoning system, escalate to human. The contract is simple: send decision context, get a verdict.
One implementation: VectorCourt — adversarial reasoning where multiple models spar under branch pressure and produce a structured verdict. It serves as a court of appeal for genuine ties, not a default path for routine decisions. Any structured reasoning service works at this layer — the important thing is that agents have some appeal route when local heuristics fail, rather than guessing or stalling.
API-first is a communication protocol. It answers: "here is how to call me."
ANCC is a behavioral contract. It answers: "here is how to use me safely without thinking."
The difference matters because the consumer is different. A developer calling an API brings context, judgment, and the ability to read between the lines. An agent calling a tool brings none of that. Everything the agent needs must be in the contract, or it will be guessed — and agents guess badly.
The novelty is not CLI. It is not markdown. It is not structured output.
The novelty is: designing tools assuming the user will not reason reliably.
That assumption changes everything. It is why scope boundaries exist (agents will bloat tools without them). It is why handoff contracts exist (agents will blur boundaries without them). It is why provenance classification exists (agents will trust stale data without it). It is why the kill path exists (agents will create redundant tools without it). It is why escalation exists (agents will guess under uncertainty without it).
API-first solved service-to-service integration. ANCC is solving agent-to-system interaction without supervision. And it matters economically: tokens are decision receipts — every missing constraint forces agents into open-ended exploration that burns reasoning tokens. Every ANCC convention is a decision that was already made, structurally, for free.
API-first assumes: "someone smart will fix it."
ANCC assumes: "nobody is coming to fix it."
Build accordingly.