Agents as tools: governed capability discovery

Language models think in tools: function names, descriptions, JSON parameters. HUMΛN agents already declare operations with paramsSchema in manifests; the honest next step is to expose those operations as LLM-callable tool schemas—while keeping every real invocation behind delegation and human policy.

This article describes three-layer discovery:

1. Installed agents — what is already live in the org, with structured tool shapes derived from manifests.
2. Workforce — humans (or routed roles) who can fulfill the capability when automation is wrong or unavailable.
3. Marketplace — assets that could be installed to close a capability gap.

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

---

Why “Generic Assistant” had to go

A placeholder agent that pretends to match everything lies to routers and to UX. Capability routing should return capability_gap: true with empty agent lists when nothing real matches—then layer marketplace suggestions and workforce matches on top. Honest gaps are telemetry, not shame.

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

---

POST /v1/agents/tool-schemas

The consolidated endpoint returns:

• tools — OpenAI-style function blocks + human_metadata (agent id, operation, scopes, capability URI, delegation hints).
• workforce_workers (optional) — people-shaped routes when include_workforce is true.
• marketplace_suggestions — install paths when include_marketplace is true and capability gaps exist.
• capability_gaps — normalized list of 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 four HTTP calls. ctx.call.discover({ capabilities, includeWorkforce, includeMarketplace }) wraps POST /v1/agents/tool-schemas and returns a typed DiscoveryResult.

Use it between planning and calling: discover → present tools to the model → human approves delegation → ctx.call or HTTP POST /v1/agents/call with an explicit agent + operation.

---

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 in production agents. Optional resultSchema documents outputs for testing and UI hints.

---

Governance recap

• Delegation before invoke — tool listings include required scopes; the runtime still checks grants.
• Workforce assignment — suggestions expose POST /v1/workforce/tasks patterns; assignment remains explicit.
• Marketplace install — suggestions carry install_path; humans confirm installs.

---

Closing

Capability-first routing is not “spray tools at the LLM.” It is making the answerable question—“who or what can do this, honestly?”—programmatic. 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.