Agent-friendly tool naming and leaner search payloads - #39
Merged
Conversation
Reshapes the MCP and CLI surfaces so agents and humans see the same
vocabulary, and trims the JSON envelopes so each tool response says
only what's actually useful.
MCP tool names now mirror the CLI command path (`<group>_<verb>`):
list_files → code_files
read_file → code_read
grep_repo → code_grep
package_summary → pkg_info
package_vulnerabilities → pkg_vulns
package_dependencies → pkg_deps
package_changelog → pkg_changelog
list_package_docs → docs_list
read_package_doc → docs_read
Top-level tools (`search`, `search_status`, `get_example`,
`search_language`, `feedback`) keep their names since they have no
CLI group to mirror. The mental model collapses to one rule: MCP
tool name = CLI command path with `_` separator.
The legacy symbol-search surface goes with the rename. The unified
`search` tool with `sources:["symbol"]` covers the same use case, so
the duplicate `code search-symbols` CLI command, `search_symbols`
MCP tool, `searchSymbols` service method, and their request /
response / test scaffolding are removed (~800 LOC). Internal types
follow: `SearchSymbolsKind` → `SymbolKind`, `SearchSymbolsFileIntent`
→ `FileIntent`, `SearchSymbolsResolution` → `IndexResolution`.
Search response is leaner. Hits drop the dead-weight `symbolRef` and
`fileContentHash` (no follow-up tool consumed them) and now omit
`qualifiedPath` when it equals `title` (the common case for
top-level symbols). The `query` echo drops the redundant `targets`
field, omits `compiled` when it equals `raw`, and only includes
`limit` / `offset` / `waitTimeoutMs` / `allowPartialResults` when
the caller set them. `progress` slims to status / counters /
elapsed / expiry — no more duplicating top-level fields — and is
omitted entirely on completed responses. `sourceStatus` entries are
omitted unless something actionable is reported (ignored or
incompatible filters / query features, non-healthy lifecycle
states, free-form notes). Empty arrays and default-valued scalars
fall out everywhere they don't change semantics.
Hits also lose the redundant `followUp` / `alternateFollowUps`
objects: each hit's `type` plus its `locator` already tells agents
which tool to call next, and the `search` description now teaches
that mapping in one sentence. `docs_list` entries lose the same
duplicate `followUp` / `readFile` companion objects.
`docs_read` / `docs read` gains `start_line` / `end_line` (MCP) and
`--lines 10-40` (CLI) so long pages don't blow context windows.
Slicing happens client-side for now and the response carries
`totalLines` so the next slice can be targeted.
`example` / `get_example` now surface `solution_id` as a top-level
field on the JSON payload — extracted from the markdown body URL —
so agents can pass it straight to `feedback` without scraping
prose.
The always-on tools (`get_example`, `search_language`, `feedback`)
get the structured `{error, code, retryable}` envelope used by the
capability-gated tools, so error handling is uniform across the
surface.
Smaller polish:
- `githits --help` now eagerly registers `search` / `search-status`
next to the other capability-gated groups; previous gate was
stricter than the docs claimed.
- `code files` / `code grep` show descriptive positional names
(`spec-or-prefix`, `path-prefix`, `spec-or-pattern`, …) instead of
`arg1` / `arg2` / `arg3`.
- `search` description trims an explicit syntax/qualifier table down
to a single sentence; examples stay.
- `example` / `feedback` / `search_language` MCP descriptions drop
Args/Returns boilerplate that duplicated the schema.
- `search_language` now emits compact JSON (was pretty-printed).
- `githits --no-color` no longer confuses the gated-group sniffer;
`auth status` no longer prints the env-token prefix.
- `mcp-cli-parity.md`, `tools.md`, and `cli-commands.md` updated to
the new tool names and envelope shape.
Bundle: 308 KB → ~290 KB raw (71 KB → 67 KB gzip). All 1376 tests
pass.
Patch release covering the agent-friendly tool naming and search-payload trim.
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
1 participant
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.
Summary
<group>_<verb>):code_files/code_read/code_grep,pkg_info/pkg_vulns/pkg_deps/pkg_changelog,docs_list/docs_read. Top-level tools (search,search_status,get_example,search_language,feedback) keep their names. Mental model collapses to one rule.code search-symbolsCLI command,search_symbolsMCP tool, and thesearchSymbolsservice path. Unifiedsearchwithsources:["symbol"]covers the same ground; ~800 LOC of duplicated request/response/test scaffolding goes with it. Internal type renames follow (SearchSymbolsKind→SymbolKind, etc.).symbolRef/fileContentHash, omitsqualifiedPathwhen it equalstitle, drops the redundantquery.targetsecho, and only emits request defaults /compiledquery /progress/sourceStatusentries when they carry information the caller didn't already supply. Empty arrays and healthy lifecycle states (INDEXED,CURRENT,STALE) fall out.followUp/alternateFollowUpsobjects —typepluslocatoralready tells agents the next tool to call, and thesearchdescription teaches that mapping.docs_read/docs readgains line-range support (start_line/end_lineand--lines 10-40) so long pages don't blow context windows. Response carriestotalLinesfor follow-up slicing.example/get_examplenow surfacesolution_idas a top-level field on the JSON payload so agents can pass it straight tofeedback.get_example,search_language,feedback) emit the same structured{error, code, retryable}envelope as the capability-gated ones.githits --helpshowssearch/search-statusnext to the other gated groups,code files/code grepshow descriptive positional names,searchdescription tightened,search_languageswitched to compact JSON,--no-colorno longer confuses gated registration,auth statusno longer prints env-token prefixes.Test plan
bun test— 1376 / 1376 passbun run build— cleantools/listover MCP stdio confirms the 14 expected tool namessearch,pkg info,docs list,docs read --lines,code files,code read,code grep,example --jsonagainst productionsolution_idextraction verified live (example --jsonreturns it)--helpregisterssearch/search-statuscorrectly under override and capability flags🤖 Generated with Claude Code