docs(DRC-2735): update available tools table with accurate tool list

[iamcxa]

Summary

• Add list_checks and run_check to the MCP server available tools table
• Move value_diff, top_k_diff, histogram_diff to a separate "Check types available through run_check" section — these are not direct MCP tools but accessible indirectly through preset checks
• Add MCP server modes note (server/preview/read-only) explaining tool availability
• Apply terminology guide fixes: "Run" instead of "Execute", clarify "MCP server modes" label
• Document single-environment mode for missing base artifacts (DRC-2795)

Dependencies

Merge blocker: This PR depends on DataRecce/recce#1175 (feat(mcp): add single-env onboarding mode). The single-env mode documentation in this PR references behavior introduced by that PR. Do not merge until recce#1175 is merged and released.

Context

The existing tools table listed value_diff, top_k_diff, and histogram_diff as direct MCP tools, but they are actually check types accessible only via the run_check tool. Meanwhile list_checks and run_check — which are real MCP tools — were missing from the table.

Additionally, DRC-2795 introduces a single-environment mode that changes how the MCP server handles missing base artifacts (target-base/). Previously the server refused to start; now it falls back to single-env mode where all tools work but diffs show no changes. This lowers the onboarding barrier — users only need dbt docs generate to start exploring the MCP server, and can add base artifacts later for real comparisons.

Source code evidence

All changes verified against recce/mcp_server.py:

8 direct MCP tools (not 5+3)

The list_tools() handler registers tools in two groups:

1. Always available (L149–L230): lineage_diff, schema_diff
2. Server-mode only (L233–L398): row_count_diff, query, query_diff, profile_diff, list_checks, run_check

value_diff, top_k_diff, histogram_diff are not registered as MCP tools — they are check types executed indirectly via run_check → submit_run() (L793–L799).

Server modes: only lineage_diff and schema_diff in preview/read-only

The call_tool() handler explicitly blocks 6 tools in non-server modes (L419–L431):

blocked_tools_in_non_server = {
    "row_count_diff", "query", "query_diff",
    "profile_diff", "list_checks", "run_check",
}

Single-environment mode (DRC-2795, recce#1175)

When target-base/ is missing, CLI auto-detects and enables single-env mode (cli.py L1815–L1830):

• Sets target_base_path = target_path so both environments load the same artifacts
• Diff tools return a _warning field: "Base environment not configured — comparisons show no changes"
• All 8 tools remain available; only diff results are affected

Terminology fixes

Per the project's writing-principles.md and terminology.md:

• "Execute" → "Run" (data teams prefer "run", see terminology guide: "Run dbt" not "Execute dbt")
• "Server modes" → "MCP server modes" (avoids confusion with database server, a ⚠️ Medium Confusion Term)

Linked issues

• Closes DRC-2735
• Related: DRC-2795 (single-env mode — blocked on recce#1175)

Test plan

• Verify mkdocs serve renders the updated section correctly
• Confirm all 8 direct tools are listed in the main table
• Confirm 3 indirect check types appear in the subsection with run_check note
• Verify MCP server modes admonition renders properly
• Verify single-env mode documentation matches released behavior (after recce#1175 merges)

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Updates the Recce MCP server documentation to accurately reflect which MCP tools are directly available vs which diff “check types” are executed indirectly through preset checks.

Changes:

• Adds the missing direct MCP tools list_checks and run_check to the “Available tools” table.
• Moves value_diff, top_k_diff, and histogram_diff into a dedicated subsection as additional check types executed via run_check.
• Adds a “Server modes” note describing reduced tool availability in preview/read-only modes.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[wcchang1115]

Hi kc,
Please check as we discussed.

[iamcxa]

All review feedback addressed — please see individual thread replies for details.

@wcchang1115

[wcchang1115]

LGTM, thanks!