Agents as tools: governed capability discovery

Friday afternoon: an orchestrator asks for invoice.extract. The model gets a tool list that includes a placeholder “Generic Assistant” that claims to match everything. It picks the placeholder. The call “succeeds.” Nothing useful ran. The gap was never logged.

HUMΛN’s answer is governed capability discovery — expose real agent operations as LLM-callable tool schemas, stack honest alternatives when nothing matches, and keep every real invocation behind delegation.

Scroll-stopper: Capability-first routing is not “spray tools at the LLM.” It is making “who or what can do this, honestly?” programmatic.

So that planners discover options without fake matches — and humans still approve installs, workforce assignment, and invoke grants.

Concrete routing scenario

A planning agent needs document.summarize for an uploaded contract:

ctx.call.discover({ capabilities: ['document.summarize'], includeWorkforce: true, includeMarketplace: true }) hits POST /v1/agents/tool-schemas.
Layer 1 — installed agents: If an org agent declares the operation with paramsSchema, it appears as an OpenAI-style function plus human_metadata (agent id, scopes, capability URI).
Layer 2 — workforce: If automation is absent or low-confidence, workforce_workers suggests people-shaped routes (POST /v1/workforce/tasks patterns) — assignment stays explicit.
Layer 3 — marketplace: If still a gap, marketplace_suggestions carry install_path. Humans confirm install; nothing auto-installs.
Gap telemetry: When nothing matches, DiscoveryResult.capability_gaps lists the unresolved requirement strings with empty agent lists — honest gaps are telemetry, not shame.

Then: present tools to the model → human approves delegation → ctx.call or POST /v1/agents/call with an explicit agent + operation. Discovery never bypasses the grant.

Why “Generic Assistant” had to go

A placeholder that pretends to match everything lies to routers and to UX. Capability routing should return empty agent lists when nothing real matches—then layer marketplace suggestions and workforce matches on top.

POST /v1/capabilities/batch-query can take include_marketplace=true to append marketplace_suggestions when agents are absent—additive and backward compatible.

`POST /v1/agents/tool-schemas`

Returns:

tools — OpenAI-style function blocks + human_metadata
workforce_workers (optional) when include_workforce is true
marketplace_suggestions when include_marketplace is true and gaps exist
capability_gaps — normalized unresolved requirement strings

Required scope: human_api:agents:read (read-class; still org-bound by your token).

`ctx.call.discover` in the Agent SDK

Agents orchestrating other agents should not hand-roll the HTTP shape for tool-schemas. ctx.call.discover({ capabilities, includeWorkforce, includeMarketplace }) wraps POST /v1/agents/tool-schemas and returns a typed DiscoveryResult.

Use it between planning and calling.

Schema discipline: `paramsSchema` is required

Tool quality lives in parameters. Requiring paramsSchema on each AgentOperationSpec forces manifests to be machine-auditable: no vague “pass a JSON blob” foot-guns. Optional resultSchema documents outputs for testing and UI hints.

Governance recap

Delegation before invoke — listings include required scopes; the runtime still checks grants.
Workforce assignment — suggestions expose task patterns; assignment remains explicit.
Marketplace install — suggestions carry install_path; humans confirm.

None of these layers auto-executes. They surface options; humans and policy still govern outcomes.

Closing

Three layers, zero fake matches, full provenance when something actually runs. When the gap is real, mark it — then close it with a human-approved install or a routed human worker. That is how HUMΛN stays sovereign, legible, and scalable.

Go deeper

Product: Capabilities, Workforce
Docs: Capability Graph, Workforce concepts
Community: Controlling execution lifecycle, Semantic routing, Every workflow is a capability