Second Brain

snowflake-mcp-v22-retro-bible-law-11-r38-r40-upstream-verifi

3 min read

Snowflake MCP v22 retro → Bible Law 11 (R38-R40) Upstream Verification + Realistic Census + Result Wrapping

Snowflake MCP v22 retrospective — Bible Law 11 (R38-R40) institutional learning

Pair: snowflake-mcp v21.0.0 → v22.0.2 (Bible v18.1 → v19.1.7) Date: 2026-04-25 Outcome: SIGNED at 880 honest tools (pair definition: snowflake-mcp + snowflake skill, atomic unit governed by Pairing Contract)

What happened

Initial v22.0.0 cutover shipped 75 capability-add tools. AJ-flagged audit revealed 51 used SQL function names + SHOW commands invented by pattern-extrapolation that DON’T exist in live SNOWFLAKE.INFORMATION_SCHEMA.FUNCTIONS catalog (SHOW POSTGRES DATABASES, SHOW OPENFLOW PIPELINES, SHOW CORTEX CODE WORKSPACES, SHOW CORTEX AGENT TEAMS, SNOWFLAKE.CORTEX.CODE_*, SNOWFLAKE.CORTEX.AGENT_TEAM_*, SNOWFLAKE.ACCOUNT_USAGE.SEMANTIC_AUTOPILOT_HISTORY). The empty-args Health Census missed it because Pydantic schema rejection fires BEFORE the SQL runs.

Failure root cause

Empty-args probing alone is insufficient — it catches schema bugs but NOT execution-time SQL/REST failures. Tools whose underlying upstream calls don’t exist (or use wrong syntax) PASS the empty-args census because no SQL ever runs. Compounded by FastMCP 3 throwing ValueError: structured_content must be a dict on non-dict returns (string/list responses from auto-generated client methods), which silently corrupts server transport and causes 404 cascade.

Resolution (institutional, fleet-wide)

Authored 3 new Bible rules (PR #20 on ARJ999/MCP-God-Agent-Development-Bible):

  • R38 Upstream Verification Mandate — every tool’s upstream call MUST be live-probed OR cite vendor docs URL before mcp.tool(...) registration. Pattern-inferred guesses BANNED.
  • R39 Realistic-Args Census Probing — Phase 0.5 census MUST include 4-layer probe (schema + realistic-args + response-shape + server-stability) with per-family templates (database/schema/table/role/query/prompt). Empty-args alone insufficient.
  • R40 Result-Shape Wrapping — install_annotator MUST convert non-dict returns to envelope {status, data: {rows or value}} BEFORE FastMCP packing. Mandatory in Pattern 3 reference implementation.

Cross-pair applicability

ALL pairs (Salesforce, Fivetran, Tableau, Blue, Snowflake, future) MUST adopt R38-R40 at next framework-major bump. Particularly relevant for any pair whose underlying client is auto-generated from upstream specs — those have the highest hallucination + mixed-shape return risk.

Architecture clarification baked into framework

“Pair” = MCP server + paired skill, atomic unit governed by Pairing Contract. Pair-domain work invokes the pair’s own skill (e.g., snowflake). Pair build/upgrade/audit work invokes mcp-server-development skill (which CONSULTS Bible chapters for detail). Skill = direction + playbook; Bible repo = detail chapters; Memory = behavioral feedback. Three-layer architecture now explicit in skill (line 33+ “What is a Pair?” section + skill↔Bible direction protocol).

Skill v19.1.7 operational playbook now has hard gates per phase

Phase 0 → 0.5 → 1.5 → 2 → 3 → 3.5 → 4 → 4.8 → 5 → 7 → 9 → 10 with explicit Action / CONSULT / VERIFY / GATE / STOP-IF-FAIL per step. Future autonomous agents CANNOT shortcut because each gate has a hard pass criterion.

Reference commits

Graph View

Backlinks