feat(mcp): rank option for search_documents#12
Merged
Merged
Conversation
…ed window) Slice 2 of ranking — wire it into the AI path. When results are capped, ranking makes the returned window the most-relevant matches instead of the first ones (the original motivation for ranking). - search_documents gains rank: bool = False, threaded to api.search(rank=...). - Index-gated and honest about it: ranking needs the on-disk index, but the MCP server defaults to read-only/no-index. If rank is requested and the search didn't use the index (result.used_index False), the response carries a rank_note saying results are in file order, not ranked — so the model won't present first-N as best-N. Docstring tells it to relay that note. - Default off (opt-in), consistent with detail; the model ranks for "most relevant..." style questions. - tests: rank-without-index adds note + stays file order; rank-with-index reorders (dense first) with no note; default has no note. - docs: CHANGELOG, USER_GUIDE Tools row + a fourth "want to see more" lever. Remaining slice: GUI checkbox. No version bump (Unreleased). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Robert D. Schoening <bobschoening@gmail.com>
exbuf
marked this pull request as ready for review
July 21, 2026 01:01
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.
What
Slice 2 of relevance ranking — wires
--rank(merged in #11) into the MCP path.search_documentsgains arankoption so, when results are capped, the assistant's window is the most relevant matches instead of just the first ones. This was the original motivation for ranking.Honest handling of the index gate
Ranking needs the on-disk index, but the MCP server defaults to read-only / no index. So:
rankis opt-in (default off), consistent withdetail.rankis requested but the search didn't use the index (result.used_indexis False), the response carries arank_notestating the results are in file order, not ranked — and the docstring tells the model to relay it. This prevents the model from presenting first-N as best-N (the same partial-picture guard we applied todetail/truncation).Verified
rankwithout index →rank_notepresent, matches stay in file order.rankwith index (allow_index_write) → reordered, most-relevant first, no note.TestRankParam;rankpresent in the tool schema; mypy + doc-links clean; no version bump.Docs
CHANGELOG (Unreleased), USER_GUIDE
search_documentsrow + a fourth "want to see more" lever (rank makes the capped set the best, not more).Remaining
GUI checkbox is the last slice.
🤖 Generated with Claude Code