Skip to main content
Glama

query_documents

Search indexed local documents using hybrid semantic and keyword matching; get ranked passages, sources, and parent sections for grounded answers.

Instructions

Hybrid search: semantic similarity plus a keyword boost for exact terms.

Returns results — ranked chunks with text, source, title, chunkIndex, score and parentId — sources, the distinct sources in rank order each with a hits count and a displayPath to show the user (source stays absolute and is what the other tools take), and parents, a map from parentId to section text. Use sources to answer "which documents cover this topic" without inspecting individual chunks.

A sources row carries lookAlikes when other indexed documents overlap it by 0.5 or more: up to 3, most first, each with source, displayPath, overlap (0..1, the estimated Jaccard similarity of the two texts' five-word runs: runs in common over runs in either, so a short text wholly inside a much longer one scores low) and date when known. They come from the whole index, outside scope and filters too. Overlap is measured text, not a verdict on which one is current: an older version or a sibling filled in from one template can hold other figures, so check both before quoting one.

Results are ranked and stop at topK without saying what they left out. For every document that mentions a term, how many do, or whether something is mentioned at all, use find_mentions.

text is the passage that matched and that score describes. parentId names the section it sits in — a transcript time window, a heading section, a slide, a table. Look it up in parents to read the whole section when the match alone is too small to act on. A chunk indexed before parent sections existed has parentId null and no entry; re-sync to fill it in.

A hit from a PDF file also carries pages, the page or pages of the file its text came from ("12" or "12-13"); a hit from any other source, or whose page is not certain, has none.

topK must be at least 1 and is capped at 100; a larger value is silently clamped to the cap rather than rejected.

When nothing matches because nothing could — an empty index, or a scope no indexed document is under — notice says which.

Cite what you take, so the user can verify it, in whatever language you answer: end with a Sources list, one line per document you actually used, each line just that document's displayPath copied verbatim — no [n] markers, nothing else on the line. Plain text, never a markdown link or file://.

labels ({facet: value or [values]}) and dateFrom/dateTo (YYYY-MM-DD, inclusive) narrow the search to labelled documents when the corpus has a classify.toml; status lists its facets and values under labels — map an approximate name to a value from there. filterCounts then says how many documents in scope were left out only for having no label or no date; each sources row carries its labels and date.

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": "query_documents"
  }
}

Input Schema

NameRequiredDescriptionDefault
topKNo
queryYes
scopeNo
dateToNo
labelsNo
dateFromNo

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv1.0.0
    • addedInput schema / properties / dateFrom
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null
      +}
    • addedInput schema / properties / dateTo
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null
      +}
    • addedInput schema / properties / labels
      Added value: +{
      +  "anyOf": [
      +    {
      +      "additionalProperties": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "items": {
      +              "type": "string"
      +            },
      +            "type": "array"
      +          }
      +        ]
      +      },
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null
      +}
  2. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

With no annotations at all, the description carries the full burden and does so: it discloses silent clamping of topK above 100, the `notice` field for empty index or out-of-scope corpus, parentId null on stale chunks with the re-sync remedy, the `pages` field only for PDFs, and that lookAlikes come from outside scope and filters and are measured overlap rather than a currency verdict. It also states the mandatory citation format, which is behavior an agent must comply with.

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?

Front-loaded with the core mechanism and the primary return field, then organized by concern (results, lookAlikes, ranking limits, chunk/parent relationship, pages, topK, notice, citation, filters). It is long and a few clauses are dense, but each sentence conveys a distinct rule an agent would otherwise get wrong.

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

Completeness5/5

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

For a six-parameter hybrid search with no annotations, the definition covers the operational rules, the shape and pitfalls of each return collection, the fallback behavior when nothing matches, and the citation obligation. An output schema exists, so the description need not restate return values — and the detail it does give about `sources`, `parents` and `lookAlikes` is interpretive rather than duplicative.

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

Parameters4/5

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

Schema description coverage is 0%, so the description must compensate, and it does for most parameters: topK's minimum, cap and silent-clamp behavior; labels as {facet: value or [values]} with a pointer to `status` for valid values; dateFrom/dateTo as inclusive YYYY-MM-DD. `scope` is only referenced obliquely ('outside scope and filters too', 'a scope no indexed document is under') without stating its accepted forms, which the schema leaves as string-or-array, and `query` is never described.

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?

Opens with a specific verb and mechanism: 'Hybrid search: semantic similarity plus a keyword boost for exact terms.' An agent immediately knows this is a ranked retrieval tool, and the contrast with find_mentions (coverage/counts) further pins down its role.

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?

Gives explicit when-to-use routing: 'Use `sources` to answer "which documents cover this topic" without inspecting individual chunks' and 'For every document that mentions a term, how many do, or whether something is mentioned at all, use find_mentions.' It also names the exclusion — results stop at topK without saying what they left out — which is exactly the boundary condition an agent needs.

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