Available Tools¶

Cerebro MCP exposes a large static tool surface spanning discovery, governed metrics, query execution, visualisation, on-chain RPC, multi-phase workflows, and interactive mini-apps — plus a small set of dynamically registered SQL tools. This page is the categorised reference; for step-by-step recipes see the Usage Guide, and for individual workflow walk-throughs see Workflows.

192 static tools across 8 packages, plus 7 dynamic SQL-templated tools from custom_tools.yaml.

Analytics¶

The raw data-warehouse surface: dbt model discovery (search_models, discover_models, get_model_details), exact schema inspection (describe_table — call it before writing SQL), and query execution. Use execute_query for synchronous exploration (< 30s) and start_query + get_query_results for long-running queries; save_query / run_saved_query persist and replay SQL by name. This package also carries the metadata helpers (docs search, platform constants, token metadata, address resolution), deterministic networkx lineage (get_upstream_lineage, get_downstream_impact), the DuckDB + Parquet simulation sandbox tools (registered when SANDBOX_ENABLED=true), and the Model Lineage Explorer mini-app.

Agent Knowledge (agent_knowledge.py)

Custom query tools (custom_queries.py)

Model discovery & lineage (dbt.py)

Lineage graphs (lineage_graph.py)

Unified listing (list_unifier.py)

Metadata & reference (metadata.py)

Model Lineage mini-app (model_lineage_app.py)

Query execution (query.py)

Async queries (query_async.py)

Simulation sandboxes (sandbox.py)

Saved queries (saved_queries.py)

Schema & sampling (schema.py)

Semantic¶

Governed metrics and semantic-layer routing (registered when SEMANTIC_ENABLED=true). Prefer query_metrics over raw SQL whenever an approved metric covers the question — it runs the canonical, pre-validated query (see Semantic Metrics). The find router is the recommended first call for almost any analytical question, and preflight_analytics_request is the hard gate in front of chart/report generation. The package also hosts the Data Catalog (search-first browse over models, metrics, and glossary terms, with Elementary-backed run/test health) and the Graph Explorer mini-app.

Data Catalog (data_catalog.py)

Data Tools (data_tools.py)

Discovery router (find.py)

Governed metrics (semantic.py)

Ui Tools (ui_tools.py)

Visualization & Reporting¶

Charts, reports, dashboards, and the mini-app plumbing. generate_charts is the batch chart generator (always ≥ 3 charts in one call — required for reports); generate_chart / quick_chart are for one-off scratch plots; the *_metric_chart* variants are driven by metric names instead of raw SQL. Three report layouts exist: dashboard (generate_report), research essay (generate_research_report), and scrollytelling case study (generate_case_study_report) — see Report Generation and Quality Gates for the enforcement rules. The package also carries the Metric Lab and Portfolio mini-apps, export_report (docx / pdf / pptx), and the Grafana dashboard publishing family (registered when GRAFANA_TOOLS_ENABLED=true).

Charts & reports (charts.py)

Cow Explorer (cow_explorer.py)

Dashboard builder (dashboard_builder.py)

Governance Explorer (governance_explorer.py)

Grafana publishing (grafana.py)

Metric Lab mini-app (metric_lab.py)

Mini-app infrastructure (mini_apps.py)

Portfolio mini-app (portfolio.py)

Report Studio (report_studio.py)

Web3¶

Direct read access to EVM contracts via JSON-RPC. Prefer the single-call tools (contract_explore, contract_call_function, contract_decode_transaction_input, contract_decode_receipt_logs) over dbt for single-address current state — dbt is for sweeps, historical data, USD conversion, and aggregations. The Contract Explorer mini-app wraps the same engine as an interactive surface. For bulk work — sweeping logs, batched view calls, storage slots, bytecode classification, or trace scans across thousands of addresses — the rpc_scan_* / rpc_batch_call family (registered when RPC_SCAN_ENABLED=true) streams results into ClickHouse scratch tables for SQL analysis; see RPC Scans. Archive reads (non-latest blocks) and trace scans require GNOSIS_ARCHIVE_RPC_URL.

Contract Explorer mini-app (contract_explorer.py)

Contract inspection (rpc.py)

Bulk RPC scans (rpc_scan.py)

Governance¶

Verification, reasoning traces, and the agent-persona loader. verify_numbers cross-checks a numerical claim against fresh SQL; get_agent_persona(role) loads one of the 28 persona contracts (the cerebro_dispatcher persona is the front door for non-trivial requests — see Dispatcher). The reasoning tools (set_thinking_mode, log_reasoning, get_reasoning_log, get_performance_stats) manage the 30-day reasoning trace, and the model-exclusion family (record_model_exclusion, exclude_module, …) satisfies the discovered-model-coverage gate that generate_report enforces.

Agent personas (agents.py)

Verification (cross_check.py)

Reasoning & tracing (reasoning.py)

Research Workflow¶

Multi-phase research projects: plan → execute → verify per phase, with findings, memory notes, evidence bindings, schema snapshots, and a peer-review gate before publish_research_report flips the workflow to complete. Every step appends to the durable event log, so a crashed project resumes where it stopped. See Research Projects for the end-to-end recipe.

Research workflow (research.py)

Storyteller Workflow¶

The narrative-first deliverable pipeline (Storytelling with Data): context brief → big idea → storyboard → per-scene visual specs → final story, with clarity and accessibility gates before storyteller_generate_story_report emits the report. Phase order is enforced in a state machine — skipping a gate raises an error. See Storyteller.

Storyteller workflow (storyteller.py)

Workflow Resume¶

Crash recovery over the SQLite event log (registered when WORKFLOW_RESUME_TOOLS_ENABLED=true). list_resumable_workflows enumerates running / waiting-gate workflows, and get_workflow_resume_hint / recompute_workflow_resume_hint return a structured "here is where you stopped, do this next" payload. The underlying event store records workflow state regardless of this flag — it only gates the user-facing tools. See Resumable Workflows and Memory & Resume.

Workflow resume (resume.py)

Dynamic Custom Tools¶

Beyond the static surface, Cerebro registers SQL-templated tools from a YAML file at startup (the MCP Toolbox pattern). Each entry in custom_tools.yaml declares a tool name, description, typed parameters, a target database, and a parameterised read-only SELECT; the server registers each one as a first-class MCP tool when CUSTOM_TOOLS_ENABLED=true (with CUSTOM_TOOLS_PATH pointing at the file). This is how the bridge-flow, validator-history, and Gnosis Pay helpers ship — curated, pre-divided (wei/Gwei-safe) queries that are cheaper and safer than having the model re-derive the SQL. list_custom_tools() enumerates the set loaded in the current build; dynamic tools are auto-classified read_only in the security registry.

Tool-classification rules¶

Every tool is classified by risk class; the classification drives the audit log and Prometheus counters. See Security & Audit for the full rules.