fix(mcp): correct the search_notes examples in the tool description - #1386
Merged
Conversation
This was referenced Aug 30, 2026
The examples were wrong in two ways:
- Argument order. The signature is search_notes(query, project, ...) but
all 27 examples read search_notes("my-project", "keyword"), which binds
the project name to `query` and the keyword to `project`. Anyone who
copies them searches for the project name inside a project named after
the query. Examples now pass the query positionally and the project as
a keyword.
- Escapes. The phrase-and-keyword example was written with \"exact
phrase\" escapes, which Python resolves at module load, so the runtime
docstring read search_notes(""exact phrase" AND keyword", ...) — not
valid Python. Single outer quotes keep the rendered call valid.
Scope note: the decorator passes its own short description=, so MCP
clients never received this docstring. It is the developer reference and
what any documentation generator reads (the Codex review of #1380 found
both bugs through exactly that path — thanks @FBISiri).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014pmKq6bqCi6Zp6BTHuZjrp
Signed-off-by: phernandez <paul@basicmachines.co>
phernandez
force-pushed
the
fix/search-notes-docstring-examples
branch
from
August 30, 2026 17:06
4e53aa0 to
cf041d1
Compare
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
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
Fixes the
search_notesdocstring examples.Why
Two bugs, both surfaced by the Codex review of #1380 (thanks @FBISiri — the doc generator there reproduced the docstring faithfully, which is how they became visible):
search_notes(query, project, ...), but all 27 examples were writtensearch_notes("my-project", "keyword"), binding the project name toqueryand the keyword toproject. Anyone copying them searches for the project name inside a project named after the query. Examples now readsearch_notes("keyword", project="my-project").search_notes("\"exact phrase\" AND keyword", ...)— Python resolves the\"at module load, so the runtime docstring readsearch_notes(""exact phrase" AND keyword", ...), which is not valid Python. Nowsearch_notes('"exact phrase" AND keyword', project="research").Scope note:
@mcp.tool(description=...)passes a one-line description for this tool, so MCP clients never received the docstring — this is the developer reference and the input to any documentation generator (the manual's planned registry generator included). Verified by listing the tools from the server:search_notesships a 79-character description.Split out of #1385, which is being redirected into the manual work (#610 / #952) rather than landing a separate doc generator; this fix stands on its own.
Not in this PR
delete_note.pyandedit_note.pyerror messages carry the same class of wrong-order examples (search_notes("{project}", "{identifier}"),read_note("{project}", ...),delete_note("{project}", ...)), with unit tests asserting on the strings — and unlike this docstring, those are runtime text a model reads. Separate fix.Verification
uv run pytest tests/mcp/test_tool_search.py— 66 passedruff check/ruff format --checkonsearch.pycleanast.parse("search_notes('\"exact phrase\" AND keyword', project='research')")🤖 Generated with Claude Code
https://claude.ai/code/session_014pmKq6bqCi6Zp6BTHuZjrp