refactor: polish MCP instructions and tool descriptions - #65
Merged
Conversation
Open-beta polish pass on agent-facing copy. The MCP server-level instructions now lead with a 4-bucket decision tree replacing the previous dense trigger-criteria paragraph, and the package/code-tools bullets are reordered to match how an agent navigates from a stack trace: search -> code reading (grep, read, files) -> docs -> package metadata. Per-tool descriptions normalized for consistency. The `format` parameter `.describe()` shares a base sentence across the 13 tools with tool-specific exceptions preserved verbatim (range semantics on `docs_read`, errors-stay-JSON on `code_files`/`code_grep`, `solution_id` contract on `get_example`, snapshot-tested-contract note on `search`). The `feedback` tool references `get_example` explicitly; `code_grep` acknowledges regex support; `code_read` allows direct-path use (e.g. from a stack trace); `search_status` bridges the camelCase `searchRef` response field to the snake_case `search_ref` parameter. Registry coverage strings now derive from canonical `PKGSEER_REGISTRY_ARGS` order. The hand-rolled `SUPPORTED_DEPS_REGISTRIES_HUMAN` constant is replaced with `SUPPORTED_DEPS_REGISTRIES_LIST` filtered from the source of truth, eliminating an order-drift class. The `pkg_info`, `pkg_deps`, and `pkg_changelog` descriptions and the CLI `pkg deps --help` align to the canonical proper-cased order. The instructions test suite gains structural invariants for decision- tree presence, bullet ordering, and tip placement; the mention to registration test stays strict. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The backend dropped the `solution_id` requirement on `/feedbacks`, so feedback can now be either solution-tied (anchored to a prior `get_example` result via `solution_id`) or generic (omit the field to send feedback about any tool — `search`, `code_*`, `docs_*`, `pkg_*` — or the overall experience). Surface changes: - `FeedbackParams.solutionId` is now optional. The wire body sends `solution_id: null` when absent, matching the existing `feedback_text` null-on-omit convention. - The MCP `feedback` tool schema marks `solution_id` optional and documents both modes; the parameter description explains when to anchor versus go generic, and `feedback_text` notes it is strongly recommended in generic mode. - The CLI `feedback` command takes `[solution_id]` as an optional positional. Help text and examples cover both modes. - The MCP server-level decision tree (bucket 4) is broadened to call out generic-mode coverage of the indexed tool surface. Tests gain generic-mode cases at every layer (service-level wire shape, MCP tool handler, CLI action). 1629 pass, smoke clean. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Switches the generic-feedback wire format from sending
\`solution_id: null\` to omitting the key entirely. Both shapes
work against the backend; key-absent is the cleaner contract since
the field is now conceptually optional rather than nullable.
Verified end-to-end against production:
bun run ./src/cli.ts feedback --accept -m "..."
-> "Feedback submitted successfully"
bun run ./src/cli.ts feedback --reject -m "..." --json
-> {"success":true,"message":"Feedback submitted successfully"}
The service test now asserts the key is absent (\`"solution_id" in
body\` is \`false\`) rather than \`null\`. Solution-tied wire shape
is unchanged. \`feedback_text\` keeps null-on-omit since backend
infrastructure was already shaped that way.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Three small fixes from running the new instructions against a real
agent session, each chosen to improve agent UX without inflating
tool descriptions:
1. Dedupe identical warnings in `search` envelopes. When N hits
share a target+freshness state, the per-hit freshness composer
used to emit the same string N times ("served stale npm:zod@4.4.3
while ... indexes" repeated five times in the live test). The
`combineWarnings` aggregator now collapses through a Set, so the
agent sees one signal per condition while parser warnings stay
pinned at the head.
2. `code_read` cap-hint suggests the next `start_line` concretely.
When a read is truncated, the existing hint reported what was
returned vs. requested but left the agent to compute the next
call. Now appends "To continue, retry with start_line=${endLine
+ 1}." — same hint surface, no schema change, just removes the
math on the agent's side.
3. `search` no-target error names both parameters. The validation
already fires client-side via `resolveTargets`, but the message
said only "At least one target is required." Now reads "Provide
either `target` for one search target or `targets` for multiple;
neither was set." so an agent reading the envelope can fix the
call without re-reading the tool description.
Tests updated and added for each change. 1630 pass, smoke and build
clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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
search→ code reading → docs → package metadata).docs_read, errors-stay-JSON oncode_files/code_grep,solution_idcontract onget_example, snapshot-tested-contract note onsearch).feedback,code_grep,code_read, andsearch_statusgot targeted UX fixes from the round-2 review.PKGSEER_REGISTRY_ARGSvia a newSUPPORTED_DEPS_REGISTRIES_LISTconstant, eliminating order-drift risk between the canonical source of truth and the hand-rolled lists inpkg_info/pkg_deps/pkg_changelog/pkg deps --help.Test plan
bun test— 1626 tests pass, including new structural invariants inmcp-instructions.test.ts(decision-tree presence, bullet ordering, tip placement)bun run smoke:mcppasses unauthenticatedbun run smoke:clipasses unauthenticatedbun run buildsucceedsNotes
code_readdirect-path framing,list-fileslead-with-routing-signal,code_grepregex acknowledgement, and thesearchRef/search_refcasing bridge.--helptext is intentionally out of scope (different audience, not loaded into agent context). Onlypkg deps --helpwas touched, and only because it shares the registry-list constant.🤖 Generated with Claude Code