A tool name is not enough

If capability resolution is treated as a first-class platform layer, its output should be more than the name of a tool.

A tool name tells the agent what it might call. It does not explain why the tool is a fit. It does not describe the required permission. It does not surface risk. It does not identify matched constraints or conflicts. It does not show whether the result came from a curated catalog, a runtime search, a policy rule, or a fallback.

For a small demo, that may be acceptable. For an enterprise agent system, it is not enough.

The resolution layer should return a structured decision package. That package should help the agent act, help the platform govern, and help operators debug.

Ranked candidates

The first output should be ranked capability candidates.

A resolution layer should rarely assume there is only one possible capability. Enterprise environments often have overlapping tools, regional variants, legacy systems, experimental workflows, and different levels of operational maturity.

Ranking lets the system express preference without hiding alternatives. It also gives the agent or orchestrator a safer way to proceed when the top candidate is unavailable, unauthorized, or risky.

This turns tool selection from a hidden guess into an inspectable decision.

Fit score and reason

A ranked list is more useful when it includes a fit score and a reason.

The fit score does not need to pretend to be mathematically perfect. Its purpose is to communicate confidence and relative strength. The reason should explain the main signals: intent match, task match, capability description, metadata, environment context, or prior usage patterns.

The goal is not to make the agent blindly trust the score. The goal is to make the selection legible.

When something goes wrong, teams should be able to inspect why a capability was recommended. Without that explanation, every failure becomes harder to debug.

Required auth and risk level

Enterprise systems need to know whether a capability is allowed before execution.

A resolution result should include required authentication, permission level, approval requirement, and risk level. Some capabilities are read-only. Some mutate production systems. Some access sensitive data. Some trigger workflows that are difficult to reverse.

The agent should not discover those boundaries only after attempting execution.

Surfacing auth and risk during resolution gives the orchestrator a chance to ask for approval, choose a safer capability, or stop before an unsafe action happens.

Source, constraints, and conflicts

A useful resolution result should show where the recommendation came from.

The source might be a curated registry, an MCP server catalog, an internal platform index, a workflow repository, a policy rule, or a previous resolution trace. Source matters because trust is not uniform. A curated production capability should not be treated the same as an experimental script.

The result should also include matched constraints and conflicts.

Matched constraints explain why the capability fits the current task. Conflicts explain why it may not. A capability may match the intent but fail the region. It may support the task but require a permission the user does not have. It may be powerful but too risky for the current environment.

Those conflicts should be visible before execution.

Suggested handoff instruction

Capability resolution should not execute the tool, but it can prepare the handoff.

A suggested handoff instruction tells the downstream agent, workflow, or tool executor how to proceed. It can include the selected capability, the reason for selection, required parameters, known constraints, approval needs, and fallback options.

This reduces ambiguity at the boundary between resolution and execution.

The point is not to over-control the agent. The point is to give the agent a better starting point.

Resolution trace

The final output is the resolution trace.

A trace should show what the system considered, what it selected, what it rejected, and why. This is essential for debugging, evaluation, governance, and continuous improvement.

Without a trace, platform teams are left with agent transcripts and tool logs. Those are useful, but they do not always explain the decision that happened before execution.

A resolution trace creates a feedback loop. Teams can improve metadata, ranking, policy rules, permission models, and capability descriptions. They can see recurring failure patterns. They can distinguish between model failures, execution failures, and resolution failures.

That distinction is critical for building reliable enterprise agent systems.

The contract matters

A good capability resolution layer should return a structured package that includes:

This contract matters because it turns capability selection into a platform concern rather than an incidental prompt decision.

Agents still need to reason. Tools still need to execute. Workflows still need to be owned by the teams that operate them. But between intent and execution, the enterprise platform needs a place to resolve what should happen next.

That place is the capability resolution layer.