Skip to main content
Glama
Sign In
semantic-search

semantic-search

by kengo006
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

semantic_search_deep

Retrieve passages that plain recall misses by widening each hit into its surrounding passage and reranking candidates to return the best few.

Instructions

Deep recall: retrieve wide, widen each hit into its surrounding passage, then rerank with a cross-encoder and return the best few.

Use this deliberately, not by default. It is for one situation: the passage you need is in the corpus but sits below the plain-recall cutoff - the twentieth hit rather than the third. When plain recall is already precise, reranking can scatter it just as easily as it can help.

⚠ score here is a reranker logit, not a cosine. It orders the results and nothing else: there is no value at which it becomes "relevant", and scores from different queries are not comparable. recall_score keeps the original cosine alongside it. ⚠ Recall layer only, exactly as with semantic_search: verbatim quotes, page numbers and emphasis are verified against the source PDF, never cited from here.

⚠ First call downloads ~2.3 GB (the ONNX graph plus its external weight file) and is slow; later calls reuse the cached model. That is ten times the embedding model this project fetches by default - worth knowing before you invoke this rather than after. Requires the LanceDB backend. Point SEMANTIC_RECALL_RERANKER at a smaller cross-encoder if that is too much.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "semantic_search_deep"
  }
}

Input Schema

NameRequiredDescriptionDefault
kNo
queryYes

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.5.2

TDQS

A4.4/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so well: it discloses that scores are reranker logits with no absolute relevance threshold and are not comparable across queries, that this is a recall layer only whose quotes/pages must be verified against the source PDF, that the first call downloads ~2.3 GB and is slow, and that it requires the LanceDB backend with an env-var escape hatch for a smaller model.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The summary sentence is front-loaded and the warning blocks are visually scannable, with the usage rule before the caveats. Some phrasing is padded ('worth knowing before you invoke this rather than after', 'ten times the embedding model this project fetches by default'), which costs a bit but does not bury the key points.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return structure needn't be spelled out, and the behavior, cost, backend requirement, and score semantics are all covered for a two-parameter retrieval tool. The remaining hole is parameter meaning (what k controls and its bounds), which the description never addresses.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and neither parameter is named or explained; 'query' and especially 'k' (default 8) are left entirely to the schema's bare integer/string types. Only an indirect hint exists ('return the best few' implies k is the number returned, while 'retrieve wide' suggests an internal widening factor that is never exposed), which is not enough to compensate for zero coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence gives a specific pipeline: wide retrieval, expansion of each hit into its surrounding passage, cross-encoder rerank, return top few. It explicitly contrasts this with plain recall and names 'semantic_search' as the sibling it mirrors, so an agent can distinguish it without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states both the when and the when-not: use deliberately only when the needed passage sits below the plain-recall cutoff (the twentieth hit rather than the third), and avoid it when plain recall is already precise because reranking can scatter good results. That is an explicit routing rule with a named alternative behavior.

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

Deploy Server

Other Tools