Search local Markdown notes by keyword to locate matching snippets with surrounding context before reading full notes. Use it to find relevant passages, not to read entire notes.
按关键词全文检索本地笔记，返回命中行前后各若干行的片段（每篇最多 3 段），总长度不超过 8000 字符。适合先定位再精读；不要用它读整篇笔记，那是 read_note 的职责。
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the disclosure burden and does well: it describes the snippet-based return format, the 3-segment-per-note cap, and the 8000-character total limit, which are real behavioral constraints an agent must plan around. It does not mention permissions, indexing scope, or error behavior, which keeps it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences with the capability and constraints up front and the alternative routing at the end; no filler and the most important limit information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema or annotations exist, and the description compensates by describing the returned snippet format and size caps, which is the key unknown for a search tool. The remaining gap is the undocumented limit parameter, which leaves an agent guessing at result-count control.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain the parameters, but it never mentions 'limit' or its default of 5, nor does it clarify query syntax beyond 'keyword'. Only the implicit notion of a keyword query is conveyed, leaving half the parameters undocumented anywhere.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb and resource (full-text keyword search over local notes) and specifies the return shape (snippets, max 3 segments per note, 8000-character cap). It also explicitly separates itself from read_note, so an agent can distinguish the two without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
States the intended workflow (locate first, then read in detail) and names the alternative for the opposite case: do not use it to read a whole note, that is read_note's job. Both when-to-use and when-not-to-use are given explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.