Using the three ouroboros_* tools

clawql-ouroboros is a specification-first TypeScript library: validated Seeds, Wonder / Reflect hooks, an EvolutionaryLoop (execute → evaluate per generation, then optional ontology-driven evolution), and an EventStore for lineage. When you set CLAWQL_ENABLE_OUROBOROS=1, clawql-mcp registers three MCP tools from clawql-ouroboros/mcp-hooks: ouroboros_create_seed_from_document, ouroboros_run_evolutionary_loop, and ouroboros_get_lineage_status. This page explains how they chain together, why that helps agents, and gives a full worked example (including optional route hints into search / execute).

Deep dive (library, in-process loop, poller, Zod hooks): clawql-ouroboros.md. ADR: 0001-ouroboros-workflow-engine.md. MCP matrix: mcp-tools.md § ouroboros_*. Agent skill: clawql-ouroboros-workflows.

What clawql-ouroboros and the three MCP tools are

The shipped Wonder / Reflect / Executor / Evaluator defaults are conservative and stubby (no external LLM) so the loop is runnable out of the box; replace engines when embedding the library in your own service (clawql-ouroboros.md § package entrypoints).

How the three tools fit together

Typical agent flow:

1. Crystallize — Ingest or paste a spec fragment, ticket body, or design note → ouroboros_create_seed_from_document → structured Seed JSON.
2. (Optional) Attach intent — If you want the default executor to call ClawQL’s internal search / execute, push route hint objects into seed.brownfield_context.context_references (see Route hints). The factory seed from create uses plain string references (document id); merge hint objects before run when you need API routing.
3. Evolve — ouroboros_run_evolutionary_loop with { seed, maxGenerations, convergenceThreshold }.
4. Inspect — ouroboros_get_lineage_status with { "seedId": "<lineageId>" } to see each generation’s execution_output, evaluation_summary, and phase.

That is spec-first iteration with a paper trail: not only the final answer, but how the loop moved through generations (clawql-ouroboros.md § core concepts).

Why use evolution and lineage

• Bounded refinement — maxGenerations caps cost and output volume; convergence and acceptance criteria gate when to stop instead of one-shot prompting.
• Traceability — ouroboros_get_lineage_status supports review, postmortems, and compliance-style “what evidence did we use?” narratives (docs/recipes/ouroboros-recipes.md § lineage tracking).
• Separation from raw kubectl / Helm — Use Ouroboros for spec-level acceptance and document-grounded evolution; keep infra blast-radius changes in normal change management (clawql-ouroboros-workflows guardrails).
• Composable with ClawQL Core — Route hints let one loop reuse the same search / execute graph the rest of the agent uses (Using search and execute).

Enable Ouroboros on clawql-mcp

1. Set CLAWQL_ENABLE_OUROBOROS=1 and restart clawql-mcp so listTools lists all three ouroboros_* tools (#141).
2. Optional durable lineage: CLAWQL_OUROBOROS_DATABASE_URL or split CLAWQL_OUROBOROS_DB_* → Postgres table clawql_ouroboros_events. Without it, InMemoryEventStore resets on process exit (#142).
3. Helm: enableOuroboros / ouroborosDatabaseUrl — Helm deployment docs.

Route hints with search and execute

The Seed schema is strict; arbitrary JSON cannot live everywhere. Route hints belong in seed.brownfield_context.context_references as objects shaped like:

Execute hint (call one operationId):

{
  "clawql_execute": {
    "operationId": "listPets",
    "args": {},
    "fields": ["name"]
  }
}

Search hint (rank operations before a later generation narrows to execute):

{
  "clawql_search": {
    "query": "find pet listing operations",
    "limit": 5
  }
}

The default executor in clawql-mcp interprets these hints and records route metadata (for example "execute" or "search") in execution_output — useful in ouroboros_get_lineage_status output (mcp-tools.md). Replace listPets with an operationId from your loaded merge (Spec configuration).

Full example from document text to lineage

Step 1 — ouroboros_create_seed_from_document

{
  "documentId": "req-2026-042-on-call-metrics",
  "extractedText": "On-call dashboard must show error rate by service and region. Acceptance: p95 latency under 200ms for the metrics API. Constraints: use existing Grafana; no new SaaS.",
  "metadata": {
    "title": "On-call metrics refresh",
    "owner": "platform"
  },
  "goalHint": "Converge on a minimal Grafana dashboard plan that meets the on-call metrics acceptance criteria",
  "taskType": "analysis"
}

Assume the tool returns { "success": true, "seed": { ... } }. That seed already has metadata.seed_id, ontology fields, and acceptance criteria inferred from text.

Step 2 — ouroboros_run_evolutionary_loop

Option A — run the factory seed as-is (good for ontology / document-fidelity loops): send one MCP payload shaped like { "seed": <…>, "maxGenerations": 4, "convergenceThreshold": 0.9 }, where <…> is the entire seed object from step 1’s success response (paste verbatim; do not truncate metadata or brownfield_context).

Option B — merge route hints, then run (same seed, but brownfield_context.context_references becomes a mixed array: keep the document id string or replace with hint objects per your workflow; below shows execute-only alongside the doc id for traceability):

{
  "seed": {
    "goal": "List pets through internal execute",
    "task_type": "analysis",
    "brownfield_context": {
      "project_type": "brownfield",
      "context_references": [
        {
          "clawql_execute": {
            "operationId": "listPets",
            "args": {},
            "fields": ["name"]
          }
        }
      ],
      "existing_patterns": [],
      "existing_dependencies": []
    },
    "constraints": [],
    "acceptance_criteria": ["Return non-empty output"],
    "ontology_schema": {
      "name": "PetOntology",
      "description": "Pet listing ontology",
      "fields": []
    },
    "evaluation_principles": [],
    "exit_conditions": [],
    "metadata": {
      "seed_id": "pet-run-learn-0001",
      "version": "1.0.0",
      "created_at": "2026-01-01T00:00:00.000Z",
      "ambiguity_score": 0.1,
      "interview_id": null,
      "parent_seed_id": null
    }
  },
  "maxGenerations": 2,
  "convergenceThreshold": 0.8
}

This Option B block matches the canonical copy in mcp-tools.md and the Ouroboros library page.

Save the JSON response fields lineageId, converged, generations, status, summary.

Step 3 — ouroboros_get_lineage_status

{
  "seedId": "<lineageId from step 2>"
}

You receive the rebuilt lineage (generations, execution_output with route when hints were used, evaluation_summary, etc.) — the same structure EvolutionaryLoop appends to the EventStore (clawql-ouroboros.md § event store / convergence).

Step 4 — (Recommended) Durable narrative

Chain memory_ingest with a short insights summary and optional toolOutputs from the lineage JSON so a later memory_recall can find the converged plan (Vault memory between chats).

Production notes Postgres and safety

• Postgres is the supported path for surviving restarts and multi-instance diagnostics; see clawql_ouroboros_events in ADR 0001.
• Guardrails: keep maxGenerations low at first; treat route hints as execution intent — restrict who can author Seeds in multi-tenant settings; validate operationId values the same way you would for direct execute (clawql-ouroboros-workflows).

Related guides and references

• Ouroboros library — longer on-site reference (route hints, troubleshooting, npm).
• Using search and execute — operationId discovery before encoding hints.
• Tools — optional ouroboros_* row in the MCP table.
• packages/clawql-ouroboros/README.md — consumer-focused install and scope vs Q00/ouroboros.