Skip to content

Add anti-guessing hint to execute_sql_query MCP tool description#5

Open
jtiisto wants to merge 1 commit into
velazcod:masterfrom
jtiisto:feature/mcp-sql-hinting
Open

Add anti-guessing hint to execute_sql_query MCP tool description#5
jtiisto wants to merge 1 commit into
velazcod:masterfrom
jtiisto:feature/mcp-sql-hinting

Conversation

@jtiisto

@jtiisto jtiisto commented May 31, 2026

Copy link
Copy Markdown

What

Adds a three-line anti-guessing hint to the execute_sql_query tool description in the localdb MCP server, pointing clients to get_table_details before they write queries.

Why

The execute_sql_query docstring is surfaced verbatim as the MCP tool description that LLM clients read. Today it pitches the tool and lists a handful of example columns, but it never tells the model to confirm the schema first. The sibling tools already signpost the workflow forwardexplore_database_structure and get_table_details both say "use me first" — yet the tool a model actually jumps to, execute_sql_query, has no backward pointer and no "don't guess" instruction.

With daily_health_metrics carrying 50+ columns (only a few of which appear in the examples), a memoryless client extrapolates the rest and fails:

  • Wrong column name → hard error: Query execution failed: no such column…
  • Wrong string value → silent 0 rows (no error), so the model wrongly concludes "no data."

The change

Insert immediately after the IMPORTANT: Only SELECT… line:

Column names are non-obvious (daily_health_metrics alone has 50+ columns) — call get_table_details(table_name) to confirm exact names before querying; do NOT guess.

This closes the explore_database_structure → get_table_details → query loop at the point of use — the one place the chain wasn't signposted.

Scope & safety

  • Docstring-only — no logic or behavior change; the description re-exports on server reload.
  • The column names referenced in the hint were verified against the current DailyHealthMetric model (57 mapped columns).
  • No test asserts on this description; ruff format --check passes and the change introduces no new lint findings.

The execute_sql_query docstring is surfaced verbatim as the MCP tool description, but it lists only a few example columns and never tells the model to confirm the schema first. With daily_health_metrics carrying 50+ columns, memoryless LLM clients extrapolate column names and hit "no such column" errors. The sibling tools (get_table_details, explore_database_structure) already point forward ("use me first"); this adds the missing backward pointer from execute_sql_query to get_table_details plus an explicit "do NOT guess". Docstring-only -- no logic or behavior change; re-exports on server reload.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant