A capability is not a tool name

A tool catalog answers a narrow question: which functions can I call? An enterprise work environment must answer several others. Which business fact is the user asking for? Which source is authoritative? Which operations can fulfill the request? Which caller can use them? What must be checked after they run?

These are different axes. Adding a paragraph to every tool description does not remove the need to govern them. A capability layer gives the system a semantic object to reason about before it picks a transport or endpoint.

The difference shows up in requests like 'Who was our largest customer last quarter?' Counting customers is cheap and relevant to the word 'customer', but it does not answer the question. A good capability discovery path starts with the required evidence—transactions, dates, totals—and only then identifies the operations that provide it.

Consider a semantic operation named customer.search. The identifier says what the operation is about without necessarily revealing how it is executed. The same object can be classified along independent dimensions: domain, operation kind, risk, permitted mode, available provider, and supported exposure.

Domain answers whether the work concerns sales, procurement, finance or another area. Operation kind distinguishes search, read, analysis, preparation, execution and verification. Risk describes possible effects. Exposure indicates whether this operation belongs in the host, agent environment, UI or an external integration.

An operation can be discoverable and still not executable. A user may be allowed to search suppliers but not change bank details. A capability may have a schema for a future write without a deployed write executor. Keeping these facts separate makes the distinction visible rather than burying it in the model's prompt.

A model does not need to see every capability definition at the start of a task. A compact interface can let it search, inspect the promising options, invoke a permitted operation and retrieve a referenced result. The registry behind that interface can be larger and organized by domain-specific packs.

This does not mean replacing a keyword search with an unconstrained reasoning step. Discovery itself can have an interpretation phase: identify the user's goal, the required business entities and the evidence needed to answer. Then retrieve a small set of plausible operations, with explicit handling of unavailable options.

The price is that discovery may fail. If a capability is hidden by a bad relevance decision, the runtime must be able to represent that gap and try an appropriate alternate path. A compact interface reduces noise; it does not remove the need for observability.

MCP, an internal host call and a provider SDK can all be legitimate execution mechanisms. They are not the semantic identity of the work. If the assistant learns an ERPNext-specific endpoint name as its only concept of an order, swapping integrations becomes a language migration as well as a software migration.

Separating operation meaning from implementation gives the system a place to attach provider-specific adapters. But adapters need to honor reality. An invoice lifecycle in one ERP may not align with another; a vendor approval may have no equivalent.

A semantic layer can promise a common question, not necessarily a common answer or every possible mutation. Unsupported behavior should remain unsupported and visible.

Some architectures discover everything and rely on the final tool-call handler to deny forbidden operations. The execution boundary must indeed be robust, but discovery and context projection are also part of the product. Surfacing forbidden capabilities can create false expectations and bad plans even when the kernel denies the call.

The effective surface should follow the actor, assignment, provider state and policy. Finding a capability is not proof of permission. Permission is not proof of a successful effect. And a successful response from an adapter is not always proof that the underlying system has reached the requested state.

The architecture is more involved than a tool list. That cost is justified when the system is expected to act repeatedly on real records rather than produce isolated demos.

One way to test a capability layer is to remove an integration and add another that supports a subset of the same business operations. Which terms remain stable? What capability disappears? Does the system notice? Do policy, verification and UI behavior still make sense?

Another test is to ask a question where the tempting tool is wrong. A strong discovery path can explain the evidence it needs; it does not simply chase similar nouns.

The goal is not to invent new vocabulary for every API. It is to preserve the boundary between what work means, where it runs, and who is allowed to do it.