feat(altimate-code): experimental direct MCP data tools (Claude reasons, altimate-code supplies tools)

Draft
AN
7d ago
+283-129

Experimental ā€” draft, not for merge. It needs an altimate-code build with altimate-code mcp serve (AltimateAI/altimate-code#1543, also a draft experiment).

Why

Today this plugin hands each data task to altimate-code run. A second model does the work, and Claude Code's own reasoning loop is bypassed. This change lets Claude Code use altimate-code's data tools directly instead. Claude's model does the reasoning, so the user's Claude Code plan covers the LLM cost. altimate-code supplies read-only tools and runs no model.

What changed

MCP server. plugins/altimate-code/.mcp.json starts altimate-code mcp serve. That gives Claude Code five tools:

  • warehouse_list
  • schema_inspect, with a value profile
  • sql_execute, read-only by default
  • sql_check
  • sql_materialize, which copies data into a session-local scratch DuckDB for joins across databases

Skills.

  • New data-question skill (24 lines, generic). Inspect value profiles before choosing columns or join keys, compute in the database, materialize the small side for joins across connections, and check keys and fan-out when they affect the answer.
  • The altimate-code routing skill now answers data questions with the tools. It keeps altimate-code run delegation for long multi-step jobs such as dbt builds and migrations. The SessionStart hook and /altimate command text match.

Version and docs.

  • Version 1.1.0-experimental.
  • The README and CHANGELOG describe the requirement and the read-only limits. Read-only is enforced by the database on Postgres, SQLite and DuckDB. Elsewhere it relies on SQL classification only, so use a read-only database user.

How tested

  • Static: JSON parsing, YAML front matter, bash -n and ShellCheck on the hook script, the plugin validators, and git diff --check.
  • Live, with Claude Code 2.1.302 on Sonnet. I loaded the plugin from this branch with --plugin-dir. altimate-code on PATH was a branch build of #1543. Bash and web tools were disabled. The data was a 60-row SQLite orders table, found through project connection discovery (.altimate-code/connections.json).
    • The plugin loaded as 1.1.0-experimental, and the data-question skill was available.
    • The server plugin:altimate-code:altimate-code connected.
    • Claude answered through warehouse_list and sql_execute, and the answer was correct: cust4 and cust2 tie with 5 paid orders, and the paid orders total 12,555. The cost was $0.07.
  • Gap found: Claude first called schema_inspect with only a warehouse, to list its tables, and the tool rejected the call because table is required. A table-list mode for schema_inspect is a follow-up on the altimate-code side.
  • Not run: remote warehouses through the plugin, and the delegation path for long jobs. That path is unchanged in behaviour apart from the routing text.

Update: analyst agent and answer_commit

  • New agents/analyst.md: the analyst method as a plugin agent. Start with claude --agent altimate-code:analyst (or set it as the agent setting) to make it the main agent. It finishes with the MCP answer_commit tool and replies with the returned FINAL ANSWER: text.
  • The data-question skill's last step now uses answer_commit.
  • Needs the MCP server from AltimateAI/altimate-code#1543 (sixth tool answer_commit).
  • Codex read-only review: no P0/P1.
  • Measured on a failing-question set (18 questions x 5, Claude Code subscription, same model): plain 58/90, plugin only 56/90, plugin + analyst agent + answer_commit 58/90. All 90 trials ended with an accepted commit (14 rejected commits). Gain is limited to questions where the agent changed answers; it is not a clear win overall.

šŸ¤– Generated with Claude Code

Update 2026-10-21 (head e378906)

Shrinks the text the plugin adds to every request, one commit per piece:

  • 40a4fe2: agent, skills and docs point at the five default MCP tools (warehouse_list, warehouse_add, sql_execute with tables, sql_materialize, answer_commit).
  • b59bb98: drop the data-question skill (duplicate of the analyst agent and the server instructions; never loaded).
  • 2b53d88: shorter review and routing skill descriptions (bodies unchanged).
  • 7abc72f: analyst agent 3,798 -> 988 chars, keeping the answer-shape rules (one field per requested item, entity and related item separate) and the value/readings/policy checks.
  • e378906: SessionStart text 537 -> 215 chars.

Local Codex review at e378906: no P0/P1. Open follow-ups: restore the dbt_project.yml qualifier in the review skill description (P2) and repoint CONTRIBUTING.md from the removed skill (P3).
Internal eval (5 trials per question, 12 questions): accuracy held with these cuts; first request ~4.5k tokens smaller, most of it from running without the Skill tool.

Update 2026-10-21 (head 8e3ae4e)

  • beff95d / 8e3ae4e: one line in the analyst agent: chain dependent queries, even across connections, in one sql_execute call with IN ({{label.column}}) (server support in AltimateAI/altimate-code#1543). Local Codex review: no findings.

Update 2026-10-21 (head bce15b1)

  • b63baea: the analyst answers in plain text: one FINAL ANSWER: line giving every requested item in order (an entity and its related item both); answer_commit is optional.
  • bce15b1: the analyst starts from the connection list the server now sends at startup; warehouse_list refreshes it.
  • Local Codex review at bce15b1: no findings.

Update 2026-10-21: own task set on a real warehouse (head bce15b1, no change)

  • 10 questions of our own on BigQuery plus Postgres, 3 trials each, plain Claude Code against this plugin: accuracy 30/30 against 30/30, cost per run 17% lower with the plugin, BigQuery bytes billed 68% lower and median time at parity. With no connections configured, the analyst added them with warehouse_add in 4 of 9 runs and used Bash clients in the other 5 (all passed).