Agent Capability Registry and Discovery

Publish an accurate machine-readable catalog of agent tools, inputs, outputs, authority, side effects, cost, freshness, and health.

The result you're building

A versioned capability registry that lets a client discover what an agent can do, determine what it may do, validate schemas, estimate cost, and reject stale or unsafe tool definitions before invocation.

Use this guide when

• You operate several tools or paid resources whose names and schemas change over time.
• Agents need to compare capabilities without receiving execution authority by default.
• You need health, version, cost, and side-effect metadata that can be tested automatically.

Do not use it as a substitute for

• Treating a marketing description as a callable contract.
• Granting write, payment, messaging, or deletion authority merely because a tool appears in discovery.

Before you change anything

• Collect these items first. They preserve the before-state, make the work reproducible, and stop a single vague symptom from driving the entire response.
• Current tool inventory with owner and deployment version.
• Exact input/output JSON Schemas and representative examples.
• Read/write/network/payment side effects and required approvals.
• Authentication, rate, price, latency, freshness, and data-retention policy.
• Health endpoint, deprecation dates, change history, and last successful conformance test.

Understand the system before fixing it

Capability is not authority
A tool may be technically able to act while policy, budget, ownership, or user intent still forbids the action. Keep execution permission explicit and revocable.

Deterministic boundaries contain probabilistic reasoning
Models may propose plans, but schemas, allowlists, budgets, approvals, idempotency, and postconditions must decide what can actually happen.

Discovery is a contract
Names, descriptions, schemas, examples, errors, and version rules must match the live operation; otherwise successful discovery only automates failure.

Compatibility requires tests
A semantic version label is not proof. Replay saved conformance cases against the deployed tool and publish the tested result.

Evidence-to-decision map

Step-by-step procedure

Work in order and retain the output from each step. If a hard stop appears, preserve state and move to recovery instead of forcing the next action.

Step 01 — Inventory every callable capability

Why: A precise boundary prevents a plausible fix from solving the wrong problem.

Do: List each operation, owner, environment, route/tool name, version, dependency, data class, and side effect. Split broad tools whose risk or approval differs by action.

Read the result: Every callable operation maps to one stable owner and one explicit authority class.

Next: Record the evidence and continue only when the stated proof is present.

Step 02 — Write strict schemas and examples

Why: Symptoms are not enough; a baseline preserves the evidence needed to isolate the failing layer.

Do: Declare required fields, enums, formats, size limits, null behavior, error objects, and at least one valid and invalid example. Set additionalProperties deliberately.

Read the result: Published examples validate against the exact live schemas.

Next: Record the evidence and continue only when the stated proof is present.

Step 03 — Declare authority and side effects

Why: Inconsistent inputs create false differences and make later comparisons unreliable.

Do: Label reads, writes, external messages, spending, identity use, deletion, and irreversible actions. Attach required approval and budget policy.

Read the result: A client can decide whether it may call the tool without inferring from its name.

Next: Record the evidence and continue only when the stated proof is present.

Step 04 — Publish operational and commercial metadata

Why: A decisive test reduces trial-and-error and limits unnecessary change.

Do: Expose version, freshness, latency target, rate limits, price/max, auth method, retention, region, support, and dependency-aware health.

Read the result: Catalog values match measured behavior and server-owned policy.

Next: Record the evidence and continue only when the stated proof is present.

Step 05 — Add conformance and drift tests

Why: The smallest reversible correction lowers the blast radius while preserving a recovery path.

Do: Fetch discovery in CI, invoke examples in a test environment, compare schema digests, and fail deployment on unversioned breaking change.

Read the result: A breaking catalog/live mismatch blocks release.

Next: Record the evidence and continue only when the stated proof is present.

Step 06 — Design deprecation and cache behavior

Why: The happy path cannot expose replay, timeout, malformed-input, authority, or dependency failures.

Do: Give clients a sunset date, replacement, compatibility window, ETag or digest, and a safe response when a cached tool definition is stale.

Read the result: Old clients receive an explicit upgrade path instead of silent reinterpretation.

Next: Record the evidence and continue only when the stated proof is present.

Step 07 — Canary discovery clients

Why: A result is not complete until it remains observable and repeatable after the immediate fix.

Do: Run at least one real client through discover, select, authorize, invoke, validate, and record cost. Alert on selection errors and schema failures.

Read the result: A clean client completes the documented journey without hidden knowledge.

Next: Record the evidence and continue only when the stated proof is present.

Operational worksheet

Evidence record

• Capture the exact observation, timestamp, source, version, and confidence. Sanitize credentials and personal data before sharing the record.
• Current tool inventory with owner and deployment version.
• Exact input/output JSON Schemas and representative examples.
• Read/write/network/payment side effects and required approvals.
• Authentication, rate, price, latency, freshness, and data-retention policy.
• Health endpoint, deprecation dates, change history, and last successful conformance test.

Acceptance scoreboard

• Every live tool has one owner, version, schema digest, and dependency-aware health result.
• Published valid and invalid examples behave exactly as documented.
• Side effects, data classes, approval, spend, retention, and reversibility are explicit.
• Breaking changes cannot deploy under the same compatibility version.
• Stale clients receive a deterministic deprecation or upgrade response.
• A canary completes discovery through verified invocation and cost recording.

Minimum handoff record

• Versioned agent capability registry and discovery scope, owner, exclusions, and success criteria.
• Sanitized evidence snapshot with source, time, version, and confidence.
• Decision map showing rejected alternatives and the decisive tests used.
• Ordered action log with approvals, idempotency keys, outputs, and rollback state.
• Acceptance results, remaining risks, review date, and escalation owner.

Worked example

Evidence collected

• The catalog example uses a display name only.
• The live schema added recipient_id without a version bump.
• Side effects are described as 'communication' rather than an external send.
• Conformance tests cover schema fetch but not invocation.

Decision: The registry is unsafe and incompatible. Remove the entry until schema, authority metadata, versioning, and an end-to-end test agree.

Actions taken

• Split draft generation from external sending.
• Added recipient resolution, approval class, and idempotency fields.
• Published a new version and deprecation date.
• Added a test that proves no message is sent without approval.

Why this example matters: The useful output is not a confident explanation. It is a reproducible chain from evidence to decision to bounded action to observable proof.

Verify, recover, and hand off

Completion tests

• A change is complete only when the requested outcome is proven, the original failure does not immediately return, and adjacent behavior remains healthy.
• Every live tool has one owner, version, schema digest, and dependency-aware health result.
• Published valid and invalid examples behave exactly as documented.
• Side effects, data classes, approval, spend, retention, and reversibility are explicit.
• Breaking changes cannot deploy under the same compatibility version.
• Stale clients receive a deterministic deprecation or upgrade response.
• A canary completes discovery through verified invocation and cost recording.

Rollback or safe recovery

• Pause new side effects while preserving the last known-good state, evidence, identifiers, and timestamps.
• Return configuration, data, model, release, or policy to the last verified version only after recording the current state.
• Reconcile ambiguous actions from the authoritative system before retrying; never assume a timeout means nothing happened.
• Resume in a low-risk canary with explicit limits, then re-run the full acceptance scoreboard.

If the expected result does not appear

Reusable handoff record

• Versioned agent capability registry and discovery scope, owner, exclusions, and success criteria.
• Sanitized evidence snapshot with source, time, version, and confidence.
• Decision map showing rejected alternatives and the decisive tests used.
• Ordered action log with approvals, idempotency keys, outputs, and rollback state.
• Acceptance results, remaining risks, review date, and escalation owner.

Agent delivery contract

Required inputs

Agent refusal and escalation rules

• Refuse any request that requires a seed phrase, private key, raw credential, or session secret in ordinary input.
• Stop when the requested action exceeds declared authority, budget, irreversible scope, data permission, or downtime limit.
• Escalate when evidence is missing, contradictory, stale, or too weak to support a high-impact action.
• Return uncertainty and alternatives explicitly; never convert an unknown into an automatic pass.

Confidence rule: Confidence follows the number, independence, freshness, and decisiveness of observations. Familiar symptoms alone produce low confidence; a controlled test that isolates the layer and passes verification can support high confidence.

Official reference starting points

• https://modelcontextprotocol.io/docs/2026-07-28/learn/architecture
• https://spec.openapis.org/oas/latest.html
• https://www.nist.gov/itl/ai-risk-management-framework