Capability Registry and Tool API v2 Projection

OpenClaw (MCP skill): For OpenClaw onboarding (skills/openclaw/, ainl install-openclaw, ainl-mcp, ~/.openclaw/), see ../OPENCLAW_INTEGRATION.md.

ZeroClaw: For ZeroClaw onboarding (skill, ainl install-zeroclaw, ainl-mcp, ~/.zeroclaw/), see ../ZEROCLAW_INTEGRATION.md. This file is the capability metadata map for tools and agents generally.

This document describes the metadata-only capability registry used to surface AINL capabilities to tools and agents, and how Tool API v2 projects a subset of that registry into a machine-readable tools descriptor.

The goal is discoverability and typed description only. This slice does not change compiler semantics, runtime semantics, or execution behavior.

Unified Capability Registry (Source of Truth)

The unified capability registry lives in:

• tooling/capabilities.json (schema: tooling/capabilities.schema.json)

It contains three slices:

• adapters — adapter-level metadata (id, support_tier, lane, notes).
• adapter_verbs — adapter+verb capabilities suitable for Tool API v2 projection.
• module_skills — module-level skills.

For this slice the registry includes:

• Adapters (referencing the broader adapter inventory in tooling/adapter_manifest.json / ADAPTER_REGISTRY.json):
  • core, queue, http, memory, sqlite, fs, tools, svc, extras, agent.
• Adapter verbs (representative subset for Tool API v2 v2.0), including for example:
  • canonical/core: adapter.core.ADD, adapter.core.SUB, adapter.core.CONCAT, adapter.core.NOW, adapter.http.GET, adapter.http.POST, adapter.sqlite.Query, adapter.fs.Read, adapter.tools.Call, adapter.queue.Put
  • extension/OpenClaw: adapter.memory.put, adapter.memory.get, adapter.memory.list, adapter.memory.prune, adapter.svc.caddy, adapter.extras.file_exists, adapter.agent.send_task
• Module skills (tiny, approved set):
  • module.examples.hello
  • module.openclaw.monitor_status_advice

Each entry can also include a domain string used for high-level grouping:

• examples:
  • math, time
  • http
  • memory
  • queue
  • filesystem
  • storage
  • tools
  • coordination
  • service_health

The domain field is for discovery and grouping only. It does not change runtime behavior, semantics, or trust rails like lane and support_tier.

Adapter entries may also include optional profile hints for safe branching in hosts/workflows. Example: memory_profile can distinguish deterministic memory contracts (for example v1 vs v1.1-deterministic-metadata) from non-deterministic semantic/plugin-backed profiles.

Separately, entries can include a usage_model string that describes how consumers should think about using the capability:

• primitive — fine-grained, low-level operations (e.g. adapter verbs like core.ADD, http.GET, memory.put).
• composite — higher-level skills or workflows built from primitives (e.g. module skills such as module.examples.hello, module.openclaw.monitor_status_advice).

kind vs usage_model:

• kind is the entity type in the registry (adapter_verb vs module_skill).
• usage_model is a consumption hint (primitive vs composite) that helps humans and agents decide how to treat the capability when building plans or surfacing options, without changing runtime behavior.

In addition, entries can define a short common_pattern string:

• A plain-language usage hint for sibling selection within a domain.
• Examples:
  • key-value write, key-value read, append-only log
  • metadata enumeration, exact-key removal, ttl cleanup
  • fetch resource, send payload, enqueue message
  • read-only query, read file contents, bridge external tool
  • advisory coordination workflow

common_pattern is descriptive only and does not affect runtime behavior or semantics. It is intended to make it easier for humans and agents to pick between similar capabilities (for example, different memory.* or http.* operations) without having to deeply parse full descriptions.

Tool API v2 Projection

Tool API v2 introduces a separate, metadata-only artifact that is generated from the unified capability registry:

• tooling/tool_api_v2.tools.json (generated by scripts/gen_tool_api_v2_tools.py)

This file contains a list of tools, each with:

• id: stable identifier
• kind: "adapter_verb" or "module_skill"
• name
• description
• inputs / outputs
• effects
• lane
• support_tier
• adapter_dependencies
• safety_tags
• source.program_path for module_skill entries

Kinds

• kind: "adapter_verb" — projected from the adapter_verbs slice in the unified capability registry.
• kind: "module_skill" — projected from the module_skills slice in the unified capability registry (currently the small, explicitly-approved set).

Both are surfaced through the same metadata surface, allowing tools and agents to inspect:

• which adapter verbs exist,
• which module-level skills exist,
• their typed inputs/outputs and effects.

Scope and Semantics (Slice 4 / 4A)

Slice 4 adds module_skill entries to the Tool API v2 projection. Slice 4A adds a small corrective pass:

• keep tooling/capabilities.json as the source of truth for adapter verbs and module skills,
• generate tooling/tool_api_v2.tools.json from that registry (no hand-authored divergence),
• keep the module-skill set tiny and explicit.

Tool API v2 remains:

• metadata-only,
• without new execution or invocation routes,
• without any compiler or runtime behavior changes,
• and without planning, orchestration, routing, or policy semantics.

Module skills are discoverable alongside adapter verbs but are still pure metadata: they describe modules; they do not define how or when those modules are executed.

Reporting and Filtering

Two small, metadata-only helpers sit on top of the unified registry and Tool API v2 projection:

• Capability report (Option A):

  • CLI: python3 scripts/capabilities_report.py
  • JSON: python3 scripts/capabilities_report.py --json
  • Reads tooling/tool_api_v2.tools.json and summarizes:
    • total tool count,
    • counts by kind,
    • counts by lane,
    • counts by support_tier,
    • adapter-verb counts grouped by adapter.

• Capability filtering helper (Option B):

  • CLI: python3 scripts/capabilities_filter.py [--kind ...] [--lane ...] [--support-tier ...] [--adapter ...] [--has-safety-tag ...] [--has-effect ...] [--json]
  • Reads tooling/tool_api_v2.tools.json and returns a filtered subset based on:
    • kind (adapter_verb vs module_skill),
    • lane (canonical vs noncanonical),
    • support_tier (e.g. core, extension_openclaw),
    • adapter (for adapter verbs),
    • safety_tags (e.g. operator_only, advisory_only),
    • effects (e.g. pure, io, network, queue_write),
    • domain, usage_model, common_pattern.

Examples:

• Canonical-only adapter verbs:

  • python3 scripts/capabilities_filter.py --kind adapter_verb --lane canonical

• Extension/OpenClaw operator-only verbs:

  • python3 scripts/capabilities_filter.py --kind adapter_verb --support-tier extension_openclaw --has-safety-tag operator_only

• Module skills only, as JSON:

  • python3 scripts/capabilities_filter.py --kind module_skill --json

• List distinct metadata values (read-only discovery):

  • python3 scripts/capabilities_filter.py --list-values domain
  • python3 scripts/capabilities_filter.py --list-values safety_tags
  • python3 scripts/capabilities_filter.py --list-values usage_model --json

These tools are read-only and operate purely on the metadata artifacts. They do not invoke programs or change compiler/runtime behavior.

Operator-only adapter audit (read-only)

An operator-only adapter audit script validates that safety/trust-rail separation is reflected in the codebase: it reports where capabilities marked with safety_tags containing operator_only are used in AINL source.

• Script: scripts/operator_only_adapter_audit.py
• Source of truth: tooling/capabilities.json (uses existing safety_tags metadata; no schema or metadata changes).
• Scope: Scans examples/**/*.lang, examples/**/*.ainl, demo/**/*.lang, demo/**/*.ainl, corpus/**, tests/** and reports per-capability file paths and categories (e.g. autonomous_ops, openclaw_extension, demo, example).
• Output: Plain-text summary by default; --json for machine-readable output; --only-used / --only-unused to restrict to referenced or unreferenced operator_only capabilities.

Example commands:

• Full audit (plain text):

  • python3 scripts/operator_only_adapter_audit.py

• JSON output:

  • python3 scripts/operator_only_adapter_audit.py --json

• Only capabilities that appear in source:

  • python3 scripts/operator_only_adapter_audit.py --only-used

• Only capabilities not referenced anywhere:

  • python3 scripts/operator_only_adapter_audit.py --only-unused

The audit is read-only and is intended to validate that operator-only trust rails are actually reflected in the current codebase. It does not modify compiler, runtime, or capability metadata.