feat(mcp)!: rename pond_sql_query to pond_sql and make the tool surface route#102
Open
tenequm wants to merge 3 commits into
Open
feat(mcp)!: rename pond_sql_query to pond_sql and make the tool surface route#102tenequm wants to merge 3 commits into
tenequm wants to merge 3 commits into
Conversation
…ce route
Clients that matter (Claude Code, Codex) defer MCP tool descriptions behind
tool search, so the surfaces that actually route are the always-loaded server
instructions, the bare tool names, and an installed skill. A field-tested
misroute proved it: 'analyze this session' bound to the SQL tool via the word
'analytic' in the instructions, when the right call was pond_get(session_id).
- BREAKING: MCP tool pond_sql_query is now pond_sql - matches the pond sql
CLI verb and drops the generic 'query' attractor from the always-visible
name. No other wire change.
- Server instructions carry all routing: analyze/review/summarize a session
binds to pond_get(session_id); latest-state questions steer to
session_from=end / sort_by=recency (supersession guard); pond_sql
self-demotes to the escape hatch; cookbook detail evicted to the schema://
resources.
- Tool descriptions lead with the verbs they claim (find / read / escape
hatch) and shrink; the sql query param keeps the column lists and gains the
tool_call body-shape map ({call_id, name, params} - $.params.command).
- sql.rs error hints teach at the failure point: schema hint gains the body
shapes, timeout hint names the remote-store round-trip cost and the
pond_get alternative.
- SKILL.md rewritten: trigger verbs in the description, which-tool router,
rules that prevent wrong conclusions (absence is not proof, supersession,
remote parts cost).
- pond init installs the bundled skill with the same consent as MCP
registration (idempotent; a hand-edited copy is never clobbered without an
explicit confirm); pond skill remains the manual path.
- Cargo.toml: stop excluding SKILL.md from the package - it is include_str!'d
into the binary, so the exclusion would fail the next publish verify build.
When a pond_get session page has later messages, the page-down marker now also says conclusions may have been revised and names session_from=end / --session-from end. Guards the field-tested failure (docs/researches retrieval field test, PR #59): an agent reads an early page of a long evolving session and reports a since-overturned conclusion as current.
…rker One fat cell (tool bodies reach 56KB) defeated the inline byte budget two ways: the row-halving loop cannot drop below one row, and the table renderer pads every row to the widest cell (~5x amplification). Measured on the real corpus: a single 42,487-char tool_result cell rendered a 214,556-byte response; with the per-cell clip the same query renders 5,534 bytes and the marker names the unclipped paths (format=ndjson, or a narrower json_extract projection). Export modes are never clipped.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Clients that matter (Claude Code, Codex) defer MCP tool descriptions behind tool search. The surfaces that actually route an agent are the always-loaded server instructions, the bare tool names, an installed skill, and error messages at the point of failure - not the carefully-written descriptions nobody sees before choosing. A field-tested misroute proved it: "analyze this session" bound to the SQL tool via the word "analytic" in the instructions, when the right call was one
pond_get(session_id).This PR makes every routing surface carry its weight, and folds in the highest-leverage finding from the retrieval ergonomics field test (#59): the supersession blind spot.
Breaking
pond_sql_query->pond_sql- matches thepond sqlCLI verb and drops the generic "query" attractor from the always-visible tool name. No other wire change.What changed
Routing surfaces
pond_get(session_id); latest-state questions steer tosession_from="end"/sort_by="recency"(supersession guard);pond_sqlself-demotes to the escape hatch; cookbook detail evicted to theschema://resources.queryparam keeps the column lists and gains the tool_call body-shape map ({call_id, name, params}- a Bash command is$.params.command), fixing a real observed failure (agents guessing$.command, silently getting 0 rows).pond_getalternative.pond_getlater-messages page marker now warns that conclusions may have been revised and namessession_from="end"(the docs: pond retrieval ergonomics field test (external session) #59 core finding, verified live).Skill
partscost).pond initinstalls the bundled skill to~/.claude/skills/pond/SKILL.mdunder the same consent as MCP registration - idempotent on re-runs, and a hand-edited copy is never overwritten without an explicit confirm (+ unit test).Latent release bug
SKILL.mdwas in Cargo.tomlexcludewhile beinginclude_str!'d into the binary - the nextcargo publishverify build would have failed on the missing file. It now ships in the package (verified withcargo package --list).Verified against the real binary (local store, read-only)
shown > 1floor; table padding amplifies ~5x). Fixed in the follow-up commit on this branch: inline table cells now clip at 1000 chars with a full-value marker - the same query renders 5,534 bytes (was 214,556), verified end-to-end. Export modes are never clipped.Validation
cargo fmt --checkclean,cargo clippy --all-targets -- -D warningsclean,cargo testgreen: 195 lib + 29 bin + 49 integration, 0 failures. Rename verified end-to-end by thesql::pond_sql_over_mcpintegration test (tools/list + call over stdio MCP).