Skip to main content

Tools and Registry

Tools are the executable capabilities that agents invoke during workflow steps. Every tool call is validated against a JSON schema, routed through configurable approval policies, and executed in a sandboxed environment. The tool registry provides versioned, immutable catalogs of available tools with content-hashed integrity.

Tool execution is schema-validated and registry-backed.

Tool Registry​

  • Stored in Postgres table tool_registries.
  • Immutable and versioned with content hash.
  • Seeded via cmd/seed-registry.
  • Tool definitions support:
    • JSON schema (schema)
    • retry policy (retry_policy)
    • cost hints (cost_hint)
    • network policy (network_policy)
    • contracts (contract)
    • composite metadata (metadata.composite_steps, metadata.input_schema)

Tool Call Flow​

Tool Manager​

Source: internal/tools/manager.go

Core behavior:

  • Validates tool args against JSON schema.
  • Applies output filtering to args/results (PII, credentials, internal endpoints).
  • Enforces network policy checks before execution.
  • Executes built-in tools, MCP tools, or composites.
  • Caches compiled schemas by registry hash.
  • Enforces optional contracts (preconditions, postconditions).

Composite Tools​

Composite tools chain existing tools as a pipeline.

Defined via metadata:

  • composite_steps: ordered execution list
  • input_schema: schema for composite input

Per-step fields:

  • tool_name
  • arg_mapping (input.*, <output_key>.*, or step_N.*)
  • output_key
  • max_attempts (optional)
  • timeout_ms (optional)

Notes:

  • Steps run sequentially through the manager.
  • Non-object outputs are normalized to object payloads for mapping continuity.
  • Runtime cycle detection fails fast on recursive composite invocation.
  • Composite depth/step guardrails are controlled by:
    • CRUVERO_COMPOSITE_MAX_DEPTH
    • CRUVERO_COMPOSITE_MAX_STEPS

CLI:

  • Build/register composites with cmd/compose-tool.

Tool Contracts​

Contracts enforce invariants before and after execution.

Contract fields:

  • preconditions
  • postconditions

Supported operators:

  • exists
  • not_empty
  • matches_type
  • equals
  • contains

Postcondition policy:

  • CRUVERO_TOOL_CONTRACT_POSTCONDITION_MODE=enforce|warn

Tool Quarantine​

The immune system can quarantine tools when repeated anomaly signatures cross thresholds.

Behavior:

  • Tool execution checks quarantine status when immune is enabled.
  • Quarantined tools return controlled errors instead of running.
  • Quarantine can auto-expire (TTL) or be manually released.

Operator workflow:

  • list anomalies/quarantine with cmd/vaccinate --list / --quarantine
  • release with cmd/vaccinate --release <tool>
  • vaccinate signatures with procedural guidance via cmd/vaccinate --signature-hash ... --procedure ...

See Immune System for full lifecycle.

Built-in Tools​

Source: internal/tools/*

  • http_get
  • calculator
  • key_value_store
  • memory_write
  • memory_read
  • model_list
  • model_prefs
  • cost_summary
  • python_exec
  • bash_exec

HTTP GET Guardrails​

http_get is intended for controlled integration fetches and includes SSRF protections by default.

Default protections:

  • only http and https URLs are accepted
  • loopback/private/link-local/multicast/unspecified targets are blocked
  • hostname resolution is validated before request execution
  • redirect targets are revalidated with the same checks before follow

Operator guidance:

  • keep http_get.block_private_ips=true in tenant tool settings unless you have a narrow internal-network use case
  • use http_get.domain_allowlist to restrict outbound domains for production tenants
  • use http_get.domain_blocklist for explicit deny rules

MCP Bridge Tools​

  • MCP tools are exposed through mcp.<name>.
  • MCP server definitions load from env (CRUVERO_MCP_SERVERS).
  • Endpoint pinning can be enforced via CRUVERO_MCP_ENDPOINTS_<SERVER>.

Simulated Tools (Demo)​

Source: internal/tools/simulated.go

  • sim_argocd_status
  • sim_argocd_investigate
  • sim_argocd_fix_apply
  • sim_ticket_read
  • sim_runtime_research
  • sim_git_pr
  • sim_teams_post
  • sim_cost_regression

Approvals​

  • Any tool decision can require approval.
  • sim_* tools are forced to require_approval=true in workflow policy.
  • Tool repair policies can cap or disable repair loops per tool.