Agent Capability Registry and Discovery

The result you are building

Finished Result:

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.

Stop Before Proceeding:

Do not advertise a capability whose live schema, authorization boundary, or side effects differ from the catalog. Disable discovery for a broken or unowned tool instead of letting clients guess.

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

Start with the row that most closely matches the evidence. The first test isolates a layer; it is not permission to
make every available change.

   Evidence                 Likely layer     First decisive check            What the result means

   Tool appears but         Catalog/schem    Run the published example       Discovery metadata is stale or omits a required constraint.
   invocation rejects       a drift          against the live version
   valid sample

   Agent selects a          Description/au   Compare declared side effects   Capabilities are not separated by risk or the description is
   destructive tool for a   thority          and approval class              ambiguous.
   read task

   Same tool name           Versioning       Compare schema digest and       A breaking change was deployed without a new version or
   returns different                         version headers                 compatibility layer.
   fields

   Catalog is healthy       Health           Call dependency-aware           Liveness is being mislabeled as usable capability.
   while dependency is      semantics        readiness check
   down

   Buyer cannot             Commercial       Compare price and maximum       Cost, units, limits, or freshness are missing from discovery.
   estimate cost            metadata         work to actual call

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.

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.

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.

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.

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.

Procedure continued 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.

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.

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.

Decision rule SHIP / AUTOMATE GATE Proceed only when every required acceptance check is supported by direct evidence, rollback is available, and the remaining risk is explicitly owned. Unknown is not a pass.

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

Starting Problem:

An agent registry lists send_message, but the live tool now requires a recipient ID and sends externally without an approval field.

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.

Proof Of Completion:

A clean client discovers the new version, validates the sample, requires approval, sends once to the resolved recipient, and records the result.

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 What happened What it usually means Next safe move

Tool appears but invocation Discovery metadata is stale or omits a Run the published example against the live version rejects valid sample required constraint.

Agent selects a destructive Capabilities are not separated by risk Compare declared side effects and approval class tool for a read task or the description is ambiguous.

Same tool name returns A breaking change was deployed Compare schema digest and version headers different fields without a new version or compatibility layer.

Catalog is healthy while Liveness is being mislabeled as usable Call dependency-aware readiness check dependency is down capability.

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
       Field                           Type                   Requirement

       target                          object                 Versioned environment, resource, identity, or workflow being evaluated.

       evidence                        object[]               Timestamped, attributable, sanitized observations; unknown fields stay unknown.

       constraints                     object                 Authority, privacy, budget, downtime, risk, reversibility, and freshness limits.

       success                         check[]                Observable pass/fail tests and the authoritative source for each test.

    Returned output
       Field                           Type                   Requirement

       diagnosis                       object                 Likely layer, supporting and conflicting evidence, alternatives, and confidence.

       plan                            step[]                 Ordered bounded actions with owner, risk, expected proof, and stop condition.

       verification                    check[]                Observed pass/fail/unknown results, not inferred success from command exit alone.

       handoff                         object                 Sanitized evidence record, recovery state, remaining risk, and next review trigger.

    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