Tools

Tiers (same as the architecture diagram — full table in configuration § Feature tiers): ClawQL Core (no opt-out) — search, execute, audit, cache; default on, opt out — memory_*, Documents (ingest_external_knowledge, knowledge_search_onyx when CLAWQL_ENABLE_ONYX); default off, opt in — sandbox_exec (CLAWQL_ENABLE_SANDBOX=1), schedule, notify, hitl_enqueue_label_studio (#228), ouroboros_*. When enabled, sandbox_exec uses sandbox bridge, Seatbelt, or Docker per env (mcp-tools.md).

ClawQL exposes search, execute, ingest_external_knowledge, in-process audit and cache, and vault memory_ingest / memory_recall by default. sandbox_exec appears when CLAWQL_ENABLE_SANDBOX=1. Set CLAWQL_ENABLE_MEMORY=0 and/or CLAWQL_ENABLE_DOCUMENTS=0 to hide memory tools or the document stack. Other tools appear when optional features are enabled (see table). The data plane for upstream APIs is search then execute (OpenAPI/Discovery plus optional native GraphQL / gRPC when configured). Canonical reference with examples.

audit and cache are ClawQL Core (no opt-out). Vault memory is default-on (opt out with env). See enterprise-mcp-tools.md, Session cache, cache-tool.md. Optional schedule is available when CLAWQL_ENABLE_SCHEDULE is set — persisted jobs with typed actions; v1 action kind is synthetic HTTP checks (#76) — Schedule synthetic checks (detailed example), schedule-synthetic-checks.md, mcp-tools.md § schedule. Optional notify is available when CLAWQL_ENABLE_NOTIFY is set — Slack chat.postMessage when the Slack spec is loaded (#77) — Slack notify (quick examples), notify-tool.md (full guide), mcp-tools.md § notify. Optional hitl_enqueue_label_studio is available when CLAWQL_ENABLE_HITL_LABEL_STUDIO is set — Label Studio task import plus POST /hitl/label-studio/webhook (#228) — HITL — Label Studio (overview), hitl-label-studio.md (full guide), mcp-tools.md § hitl_enqueue_label_studio. Optional knowledge_search_onyx is available when CLAWQL_ENABLE_ONYX is set and documents are enabled — Onyx semantic document search when the onyx bundled provider is in the merge (#118) — Onyx knowledge search (quick examples), onyx-knowledge-tool.md (full guide), mcp-tools.md § knowledge_search_onyx.

search

Searches the active operation index (OpenAPI/Discovery by default, plus native GraphQL/gRPC entries when CLAWQL_GRAPHQL_SOURCES / CLAWQL_GRPC_SOURCES are set) by natural language intent and returns a short ranked list of hits. Work happens against an in-memory index inside the MCP process—full specs are not pasted into the model context.

execute

Runs a discovered operation by operationId. For OpenAPI/Discovery ops, single-spec mode prefers the in-process OpenAPI→GraphQL path so only requested fields flow back; multi-spec and some translation failures use REST directly. Native GraphQL and gRPC ops use HTTP GraphQL or grpc-js unary instead. Agents do not hand-write GraphQL for OpenAPI-backed calls; the server builds the internal document.

Typical workflow

1. search("delete a Cloud Run service")
   → top hits with operationId, method, path, parameters

2. execute("run.projects.locations.services.delete", {
     name: "projects/my-proj/locations/us-central1/services/my-svc"
   })
   → lean JSON (GraphQL-shaped or REST fallback)

See GraphQL layer for OpenAPI→GraphQL vs native GraphQL vs REST routing.

Optional tools

They do not replace execute for calling upstream APIs (except notify and knowledge_search_onyx, which wrap single operations for convenience).

Ouroboros (clawql-ouroboros)

The clawql-ouroboros package is an evolutionary loop library (Seed, Wonder/Reflect, Executor/Evaluator, convergence). With CLAWQL_ENABLE_OUROBOROS=1, clawql-mcp registers three ouroboros_* MCP tools backed by the same library; without the flag, import clawql-ouroboros from your own service. Overview, install, and examples: Ouroboros library · canonical clawql-ouroboros.md.

For guided operation via MCP, the default executor supports schema-safe route hints inside seed.brownfield_context.context_references[]:

• clawql_execute → internal execute call (operationId, args, optional fields)
• clawql_search → internal search call (query, optional limit)

Full payload examples, troubleshooting, and production rollout notes are on Ouroboros library.