mcp-local-rag

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With readOnlyHint and openWorldHint already declaring the safety profile, the description adds real value: it discloses the internal pipeline (search, local re-rank, dedupe, fetch page text) and the failure semantics (empty engines reported as warnings, retry with 'auto' if all chosen engines are empty). It stops short of disclosing cost/latency characteristics, which matters for a tool that fetches pages.

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?

Front-loaded with a pipeline summary, then a scannable backend bullet list — well structured and mostly waste-free. The bullet list is slightly long but each entry carries decision-relevant information about reliability.

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?

An output schema exists so return format need not be covered, and annotations cover the read-only/open-world profile; the description fills in pipeline and fallback behavior. The remaining gap is sibling disambiguation, which is the one thing an agent must know before choosing among the five search tools.

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 coverage is 100%, so the baseline is 3, but the description genuinely enriches the 'backends' parameter by enumerating valid values and characterizing each one's reliability and best use, which the schema's one-line description does not do. The interaction between num_results_per_term and top_k_per_term (rank N, keep K) is implied but not explicitly explained.

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?

The first sentence states a specific verb and resource ('Research a topic across several search terms and engines') and the following sentence spells out the pipeline: multi-term search, local re-ranking, deduplication, page fetching. It does not explicitly state how it differs from siblings like deep_research_google or deep_research_ddgs, though the backend list implies this tool is the superset that can target either.

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?

Backend selection guidance is concrete and actionable: 'auto' is flagged as the most reliable default, 'brave' as fast, 'wikipedia' for title-like lookups, and google/startpage/yahoo/mojeek as often blocked with an auto-retry fallback. What is missing is guidance on when to pick this tool over the sibling search tools (search, rag_search_ddgs, deep_research_google), which an agent must infer.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly and openWorld, but the description adds real pipeline detail beyond them: multi-engine querying, skipping blocked engines, local re-ranking, de-duplication, and fetching of top pages as full text — which signals latency and network cost. It does not mention rate limits, failure modes, or how many pages get fetched.

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?

Three short sentences with the backend mechanism first and the sibling equivalence last; every clause carries information an agent cannot get from the schema. No filler or repetition of annotations.

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?

An output schema exists, so return shape need not be explained, and annotations cover the safety profile. The description covers mechanism and scope well; only secondary operational facts such as cost, expected latency, or failure behavior are absent.

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 100%, so all four parameters (search_terms, top_k_per_term, num_results_per_term, include_urls) are already documented in the schema. The description adds no guidance on how many terms, how terms relate to each other, or how top_k interacts with the ranking stage, so the baseline 3 applies.

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?

States a specific operation (deep research) plus the exact backend mechanism: ddgs "auto" metasearch querying several engines per term while skipping blocked ones. It also explicitly relates itself to a sibling ("Same as deep_research with its default backend"), so an agent can distinguish it from deep_research 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?

The sentence "Same as deep_research with its default backend" gives clear selection context: this is the default/alias variant rather than a distinct capability. It stops short of naming when to prefer deep_research_google or rag_search_ddgs instead, so there are no explicit exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint/openWorldHint annotations, the description discloses real behavioral facts: Google blocks scrapers, the pipeline re-ranks and de-duplicates locally, pages are converted to text, and a ddgs fallback fires with a warning when nothing is returned. That failure-mode and fallback disclosure is genuinely useful for an agent interpreting empty or warned results.

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?

Three tight sentences, front-loaded with what the tool does and followed by the failure mode and fallback. No filler, though the trailing fallback clause could be trimmed or merged for clarity.

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?

An output schema exists so return-format explanation is unnecessary, and annotations cover the safety profile; the description supplies the pipeline, the scraping risk, and the fallback. What remains missing is guidance on choosing this over deep_research_ddgs or rag_search_google.

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 100%, so the baseline is 3. The description loosely explains the rank-then-keep pipeline that underlies num_results_per_term versus top_k_per_term, but it never ties that pipeline to the parameter names, so it adds little beyond the schema.

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?

States a concrete pipeline: each term is searched, re-ranked locally, de-duplicated, and the best pages fetched as text. The 'using only Google' scoping gives a rough handle against the ddgs siblings, but the added note that it falls back to ddgs 'auto' metasearch blurs how it differs from deep_research_ddgs.

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?

Usage is only implied: the agent can infer this is the Google-flavored deep research option versus deep_research_ddgs, but no alternative is named and no when-not condition is stated. The fallback sentence describes internal behavior rather than telling the caller when to pick this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and openWorldHint, yet the description adds genuine behavioral detail: multi-engine metasearch, automatic skipping of blocked engines, local semantic re-ranking, and a subsequent page-fetch step. This tells the agent the call may be slow and that results are re-ordered, though latency and failure modes are not quantified.

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?

Four short sentences with the core action front-loaded first and the mechanism after; nothing is redundant with the schema. The standalone "Default choice for lookups" sentence is terse but slightly orphaned from the mechanism paragraph.

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?

With an output schema present, return values need not be described, and the annotations cover the safety profile, so the description's remaining job is mechanism and default-status — both covered. The only real gap is sibling differentiation across the five related search/research tools.

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 100%, so all four parameters are already documented, which sets the baseline at 3. The description does implicitly explain the pipeline (broad initial results get re-ranked, then top pages are fetched), which clarifies why num_results and top_k are distinct, but it adds no explicit parameter-level detail.

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?

States a specific verb and resource ("Search the web and return the most relevant pages as text") and explains the underlying mechanism (ddgs "auto" metasearch over DuckDuckGo, Brave, Wikipedia). It calls itself the "Default choice for lookups," which weakly separates it from siblings, but it never contrasts the row with rag_search_google, search, or the deep_research variants.

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?

"Default choice for lookups" is an implied rule for when to reach for this tool, and the mechanism note hints at fallback behavior when an engine is blocked. However, no sibling is named as an alternative and there is no statement of when NOT to use it (e.g., versus rag_search_google or deep_research), leaving the choice to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint and openWorldHint, so the description adds real value: it discloses the local semantic re-ranking pass, that Google frequently blocks scrapers, that empty results trigger a ddgs 'auto' metasearch retry, and that a warning is emitted when that happens. This is exactly the kind of reliability context an agent needs. Return shape is left to the output schema, which is acceptable.

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?

Three tight sentences with no filler, leading immediately with what the tool does before the reliability caveat. The hard line breaks in the raw text are cosmetic and do not impede reading.

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?

For a 4-parameter read-only search tool with a full output schema and annotation coverage, the description supplies the important missing context: local re-ranking, blocking risk, and the silent provider switch. Only the lack of sibling routing guidance keeps it from being fully complete.

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 coverage is 100%, so both top_k and num_results are already documented in the schema; the description reinforces the two-stage model (rank N initial results, fetch and return the top K pages as text) but adds no syntax, format, or edge-case detail beyond that. Baseline 3 applies when the schema carries the parameter burden.

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?

States a specific verb and resource ('Search Google and return the most relevant pages as text') and adds the distinguishing trait of local semantic re-ranking. It does not, however, contrast itself against the obvious siblings (rag_search_ddgs, deep_research_google), so an agent must infer the boundary.

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?

No when-to-use or when-not-to-use guidance relative to alternatives. The only routing information is an internal fallback to ddgs on empty results, which describes runtime behavior rather than when the agent should choose this tool over rag_search_ddgs or deep_research_google.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint and openWorldHint, but the description goes much further: it discloses the multi-tier ranking pipeline, that a local embedder may run, and that the client may prompt the user to switch to full pages. That is exactly the non-obvious behavioral context an agent needs before paying the cost of this call.

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?

The lead sentence is front-loaded and the tier list is scannable, with every tier conveying the cost tradeoff. It is on the long side for a search tool, and the closing sentence about the client asking about questions is a bit convoluted, but nothing is pure filler.

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?

An output schema exists so return values need no explanation, and the description covers the remaining gaps: cost relative to siblings, fallback behavior, and where the `keywords` hint pays off. Nothing an agent needs to call this correctly is missing.

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 coverage is 100%, so 3 is the baseline, but the description adds real meaning by tying parameters into the pipeline: `keywords` is matched via BM25 alongside the query, `top_pages` bounds stage 1, and the passage mechanics explain the ~600-char split. It stops short of explaining `backend` or `num_results` beyond the schema.

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?

States a specific verb and resource ('Search the web') plus a precise output scope ('return only the passages that answer the query, not whole pages'), and explicitly contrasts itself with sibling rag_search_ddgs ('about a tenth of the text'). An agent can distinguish it from the rag_search_* siblings without opening a schema.

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?

Explicitly says 'Use this first', names rag_search_ddgs as the heavier alternative, and lays out the escalation order (cheap title/snippet filter -> fetch+BM25 -> embedder fallback). The condition that triggers the fallback path ('matches nothing, a paraphrase') is stated outright.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.