Tool Registry

The tool registry is the runtime surface that lets Compozy expose structured actions without turning every capability into a one-off prompt convention. Tools have stable IDs, JSON schemas, availability diagnostics, policy checks, redaction rules, and invocation events.

Use this page when you need to understand what a tool is, how agents discover tools, and how the operator CLI relates to the session-bound MCP tool surface.

In one sentence

An Compozy tool is a daemon-owned action with a typed input schema, a typed result, policy enforcement, and an audit trail.

Why Compozy has tools

Agent sessions need more than text prompts. They need to inspect runtime state, claim work, extend leases, read memory, search skills, inspect hooks, and report progress without scraping prose or calling private Go functions.

The registry gives those actions one shape:

• discover what exists
• inspect the schema before calling it
• invoke through daemon policy
• redact sensitive input fields
• record enough evidence for operators to audit what happened

Discovery path

compozy tool list -o json
compozy tool search memory --limit 5 -o json

compozy tool info compozy__skill_view -o json

compozy tool invoke compozy__tool_info --input '{"tool_id":"compozy__skill_view"}' -o json

Tool surfaces

Default discovery tools

The normal managed-agent path starts with discovery, not blind invocation. These canonical IDs help agents orient and inspect the registry:

• compozy__bootstrap
• compozy__catalog
• compozy__tool_search
• compozy__tool_info
• compozy__skill_search
• compozy__skill_view

For a bare managed session, hosted MCP projects the full availability-gated callable catalog. Compozy does not add an automatic bootstrap/catalog allowlist over that hosted projection. Agent definitions, session lineage, disabled sources, denylists, and approval/risk gates still narrow or block invocation.

compozy__tool_list returns only the currently callable projection. compozy__tool_search and compozy__tool_info are diagnostic: they can return known descriptors with callable or denied status so an agent can explain whether a tool is absent, unavailable, or policy-denied before falling back to CLI or HTTP.

These are canonical Compozy ToolIDs. They are stable for registry, policy, CLI, and descriptor use, but the active agent harness owns the actual invocation name. Managed agents should search or load by capability plus canonical ID, then call the tool reference surfaced by the harness exactly as returned.

The expected pattern is:

That sequence lets the agent inspect available actions and schemas before it commits to a call.

What belongs in the tool registry

Good tool candidates:

• runtime state inspection
• task claim, heartbeat, completion, failure, and release
• task bridge notification subscription management
• memory show/search/write operations
• Memory v2 operational/admin actions that already exist on CLI/API surfaces
• provider model catalog list/curation/refresh/status
• skill and capability discovery
• hook, automation, and extension lifecycle operations
• extension bundle activation and desired-state resource inspection
• MCP server probe/status diagnostics that keep login/logout on control surfaces
• bridge and network diagnostics

Poor tool candidates:

• UI-only convenience flows with no daemon state
• arbitrary shell escape hatches
• hidden aliases for behavior that already has a canonical primitive
• raw secret retrieval

Related pages

• Toolsets explains grouped exposure.
• Policy and Invocation explains validation, approvals, sensitive fields, and diagnostics.
• Oversized Tool Results explains previews, retained result artifacts, paging, workspace isolation, and retention.
• Agent Definitions explains how tools fit into agent startup.
• SKILL.md Format explains how skills teach agents when to use tools.
• Tool CLI Reference is the generated command reference.