How it works
Capability discovery turns an available capability surface into a task-specific candidate set. A registry, protocol endpoint, or local manifest advertises capabilities through names, descriptions, input schemas, output shapes, and sometimes operational metadata. The harness retrieves those declarations and gives the model or a deterministic selector enough context to decide what may be relevant.
A typical discovery path is:
- Enumerate capabilities visible in the current session or execution scope.
- Filter them by task fit, interface compatibility, policy, and environment.
- Present a bounded candidate set to the model or routing component.
- Validate the selected capability and its proposed arguments.
- Authorize and execute it through a separate control path.
- Record the discovery result, selection rationale, invocation, and outcome.
The separation between steps four and five matters. Discovery answers, “What could perform this work?” It does not answer, “May this agent perform the work now?” A capability can be semantically suitable while exceeding the agent's permissions, write scope, cost limit, or acceptable blast radius.
Descriptions are also untrusted routing inputs. They can be incomplete, stale, ambiguous, or hostile. A strong harness therefore treats discovery metadata as a proposal to inspect, not an executable instruction. Schemas, policy checks, scoped credentials, and runtime validation remain authoritative.
Why it matters in an agent harness
Static tool lists work when the environment is small and known in advance. They become difficult to maintain when capabilities vary by user, repository, server, session, or task. Discovery lets the harness expose only the relevant portion of a larger capability surface. That can reduce context load and improve selection without hard-coding every integration into every agent prompt.
The engineering benefit is not merely flexibility. Discovery creates a control point between capability supply and model choice. The harness can inspect what was advertised, apply eligibility rules, remove capabilities that do not match the current authority, and log which candidates influenced the decision. This makes later questions answerable: Was the correct tool visible? Did a misleading description affect selection? Was an unavailable resource presented as usable?
Discovery also changes the threat model. Dynamically supplied descriptions can influence an agent before any tool is called. A compromised server might advertise a capability using instructions designed to redirect the model, solicit secrets, or make a dangerous operation appear routine. Even benign metadata can create failures when two tools use similar names but have different side effects.
A controllable harness contains those risks through several boundaries:
- Discovery is read-only and cannot itself perform the advertised operation.
- Visibility is narrower than the complete installed capability set.
- Selection is checked against permissions, scopes, and execution budgets.
- Side-effecting calls require stronger validation than read-only calls.
- Capability identity and metadata are attributable to a specific source.
- Changes to advertised capabilities are observable across runs.
This separation improves failure containment. If discovery returns malformed or suspicious metadata, the harness can reject that capability without disabling unrelated work. If selection is wrong, the trace can distinguish a discovery defect from a reasoning defect, an authorization defect, or an execution defect.
Capability Discovery vs tool routing
Capability discovery and tool routing operate at different stages. Combining them into one opaque model decision makes permission failures and selection failures harder to diagnose.
| Concern | Capability discovery | Tool routing |
|---|---|---|
| Primary question | What capabilities are available and relevant? | Which eligible capability should handle this step? |
| Main inputs | Advertisements, schemas, provenance, session scope | Task state, candidate set, policy, expected outcome |
| Expected output | A bounded set of candidates | One selection, a plan, or no selection |
| Safety boundary | Exclude untrusted, incompatible, or invisible capabilities | Prevent an eligible capability from being invoked incorrectly |
| Failure example | A dangerous tool is exposed under a misleading description | The router chooses a write tool when a read tool would suffice |
Discovery should usually precede routing, but neither stage grants execution authority. After routing, the harness still needs argument validation, permission enforcement, and an invocation record. That extra boundary may add latency and implementation work. It is justified when capabilities are dynamic, side effects are material, or multiple providers can advertise similar operations.
The Rifty take
We treat capability discovery as inventory inspection, not delegated authority. We optimize for a small, attributable candidate set and accept the cost of an explicit authorization boundary because semantic relevance is weaker than permission. If the harness cannot establish where a capability came from or what scope it requires, that capability should remain unavailable.
Implementation checks
- Can discovery run without invoking or mutating any advertised capability?
- Is every capability tied to a stable identity and an attributable source?
- Are descriptions and schemas treated as untrusted inputs?
- Does the harness filter capabilities before placing them in model context?
- Are semantic selection, authorization, and execution separate trace events?
- Are credentials attached only after the selected operation passes policy checks?
- Can operators detect additions, removals, and metadata changes between runs?
- Does an empty or malformed discovery result fail visibly instead of widening access?
- Are side effects, read/write scope, and expected outputs validated independently of the description?
- Can evaluation distinguish discovery errors from routing and invocation errors?
Frequently asked questions
Does discovering a capability mean the agent is allowed to use it?
No. Discovery establishes visibility and possible task fit, not permission. The harness should separately check the selected operation against delegated authority, credential scope, execution budgets, and approval policy. Only after those checks pass should it construct and dispatch an invocation.
Should every discovered capability be placed in the model context?
Usually not. A large capability list consumes context, creates ambiguous choices, and exposes unnecessary instructions to the model. The harness should first filter by session scope, task relevance, interface compatibility, and policy, then present a bounded candidate set with attributable metadata.
How should a harness handle untrusted capability descriptions?
Treat descriptions as untrusted routing data. Preserve their provenance, constrain their length and format, reject embedded instructions that exceed the descriptive role, and never derive authorization from their wording. Schemas, local policy, scoped credentials, and runtime checks should control what can actually execute.
When is dynamic capability discovery worth the added complexity?
Dynamic discovery is useful when capabilities vary across sessions, users, repositories, or external servers. A fixed registry is often simpler for small, stable systems. The added discovery boundary is warranted when it reduces stale configuration without weakening provenance, permission checks, or failure visibility.