Capability Discovery & Negotiation — MCP & Agent Interoperability

Every useful collaboration begins with a question: what can you do? In software, that question is easy to skip because two systems may appear to speak the same language. They may both accept network calls, exchange structured messages, or expose an application programming interface, often called an API. But sameness at the surface is not enough. One system may support a newer field, a larger file, a stricter security rule, a different model, or a feature that only works in certain regions. Capability discovery is how a system finds out what is available. Capability negotiation is how two systems agree on what they will actually use.

Start with the problem: hidden assumptions

A capability is not just a feature name. It is a promise about behavior under stated conditions. “Can translate text” is a weak statement. “Can translate up to 10,000 characters from English to French, preserving markup, with a maximum latency target of two seconds” is closer to a real capability.

Hidden assumptions are where integrations break. A client assumes the server accepts a field. A server assumes the client can handle a new response shape. A workflow assumes a tool can process a file size that it quietly rejects. These are not exotic failures; they are the normal result of independent systems changing at different speeds.

Discovery and negotiation turn assumptions into explicit checks. Discovery asks, “What is possible here and now?” Negotiation asks, “Given what we both support, which option will we use for this interaction?”

Discovery and negotiation turn hidden assumptions into an explicit, agreed mode of interaction.

What a capability must say

A useful capability description answers more than “yes” or “no.” It explains the shape of the work, the limits around it, and the conditions under which the answer is valid. The goal is not to describe every internal detail. The goal is to give another system enough information to make a safe decision.

Good capability descriptions separate what is stable from what may vary. The name of an operation may be stable for years, while quotas, supported formats, or optional parameters change more often. Treating all of these as one vague feature forces clients either to guess or to hard-code behavior that will become stale.

Operation: the action the system can perform, such as search, summarize, validate, reserve, or transform.
Inputs: the required and optional data the system accepts, including formats, size limits, and validation rules.
Outputs: the data the system returns, including response shape, possible error types, and streaming behavior if any.
Constraints: limits such as rate, latency, cost, region, availability window, and maximum payload size.
Policy: authentication, authorization, data handling rules, retention, and compliance boundaries.
Version: the specific contract or behavior generation the caller is using.

Discovery can happen before or during use

Some discovery happens before a system runs. Developers read documentation, import a software development kit, or inspect a contract. This is useful because it makes design and testing possible early. But it can become stale if the running system changes faster than the documentation or deployed client.

Other discovery happens at runtime. A client may ask a service for its supported versions, read a machine-readable schema, query a registry, or make a safe probe request. Runtime discovery is more current, but it adds complexity: the caller must handle missing answers, partial answers, and different answers from different environments.

The best designs usually combine both. They use stable published contracts for planning and testing, then confirm the specific capabilities of the live endpoint before depending on optional or variable behavior.

Design-time discovery reads docs and SDKs, while runtime discovery queries the live endpoint.

Negotiation is choosing a shared mode

Negotiation begins after each side has some view of the other’s capabilities. The client may prefer the newest version, the smallest response, the cheapest model, the strongest encryption, or the fastest streaming mode. The provider may support several choices but restrict some by tenant, region, load, or policy.

The result of negotiation should be explicit. A client should know not only that the request succeeded, but which version, format, model, language, or policy was selected. Otherwise, the client may interpret the result incorrectly or fail later when an assumption no longer holds.

Negotiation is not always a conversation with many round trips. It may be a single request that lists acceptable options, followed by a response that confirms the chosen one. The important point is that both sides can explain the decision.

Trust the answer, but bound the risk

A capability claim is only as useful as its trust boundary. A public endpoint, an internal service, a browser, a device, and an artificial intelligence agent may all describe what they can do, but those claims do not carry the same weight. A caller still needs authentication, authorization, validation, and monitoring.

Discovery should not become a way to reveal sensitive information. A system may need to expose different capability views to different callers. For example, an administrator may see management functions that an ordinary user must not discover, even as metadata.

Negotiation also needs safe failure. If no shared option exists, the system should fail clearly rather than silently downgrade to an unsafe mode. A fallback is helpful only when it is allowed by policy and visible to the caller.

⚠️

Silent downgrade. The most dangerous negotiation failure is a quiet move to a weaker mode that the caller did not approve.

If a shared option exists, confirm it explicitly; if none does, fail clearly rather than downgrade silently.

What leaders and practitioners must decide

Capability discovery and negotiation are design choices, not just implementation details. Leaders decide where variation is acceptable and where standardization is cheaper. Practitioners turn those choices into contracts, tests, error handling, and observability.

A platform team may require every service to publish a machine-readable contract. A product team may choose to support two versions at a time and publish an end-of-support date for older versions. A security team may forbid fallback from a stronger protection mode to a weaker one. An operations team may require metrics that show which negotiated modes are actually in use.

These decisions prevent accidental complexity. Without them, every integration invents its own way to ask, answer, downgrade, and fail. With them, teams can evolve systems independently while still giving callers predictable choices.

A practical pattern for robust systems

Start with a small, stable baseline that every participant must support. Make the baseline useful enough that the system can still perform its core job when optional capabilities are absent. Then add optional capabilities in a way that callers can discover and choose deliberately.

Represent capabilities as data, not folklore. A human document is valuable, but machines also need something they can read: a schema, a manifest, a registry entry, or a discovery endpoint. Include version, limits, and policy where they affect behavior.

Finally, test the negative paths. Test what happens when a capability is missing, when a caller asks for an unsupported mode, when a provider removes an option, and when negotiation produces a fallback. Many systems are tested only for the happy path, even though discovery and negotiation exist mainly to manage change.

Define the baseline behavior that all parties must support.
Describe optional capabilities with machine-readable data.
Require callers to state preferences and acceptable fallbacks.
Confirm the selected mode in the response or session state.
Log negotiated choices so teams can see real usage before changing support.

✅

Good baseline. A strong baseline lets optional features improve the system without becoming hidden requirements.

Key takeaways

A capability is a behavior promise with conditions, not just a feature label.
Discovery finds what is available; negotiation selects what both sides will use.
Published contracts and runtime checks solve different parts of the same problem.
Silent downgrade is risky; fallback must be explicit, allowed, and observable.
Leaders should decide where flexibility is valuable and where standardization is safer.
A stable baseline plus discoverable optional features lets systems evolve without constant breakage.

Robust systems start from a stable baseline, add optional capabilities as data, and test the negative paths.

Glossary

Capability: A stated behavior a system can provide under specific conditions and limits.
Discovery: The process of learning which capabilities are available from a system.
Negotiation: The process by which two systems choose a mutually supported way to interact.
Contract: A documented agreement about inputs, outputs, errors, versions, and behavior.
Schema: A machine-readable description of the shape and rules of data.
Version: A named or numbered form of a contract or behavior set used to manage change.
Fallback: An alternate behavior used when the preferred capability is unavailable or unsuitable.
Registry: A catalog where systems can publish and find information about services and capabilities.
Probe: A safe test request used to confirm behavior without causing harmful side effects.