Skip to main content
Glama

find_mentions

List every indexed document that mentions a word or phrase, with counts and matched word forms, so you can see exactly which documents mention a term and how often.

Instructions

List every indexed document that mentions a word or phrase, with counts.

For "which documents mention X", "list all", "how many", and "is X mentioned anywhere": this scans the whole index, where query_documents ranks a few passages and stops.

A term matches where a word begins and its end is open: акт finds акта and актов, not контакт — but also актуально. forms lists the word forms each term matched, with how many documents have each; check it before trusting a count. A term wrapped in double quotes matches that exact word only, so to narrow, pass the forms you want, each quoted, with match="any". Case, ё/е and Unicode composition are ignored. The match is literal, so a synonym or another spelling is another term. terms is one string or a list of up to 10; match="all" keeps documents containing every term somewhere, match="any" those with at least one, and each row then lists its terms. Titles are searched too.

Returns searchedDocuments (indexed documents in scope that pass the filters), matchedDocuments, matchedChunks, forms, and documents: title matches (inTitle) first, then by hits, the chunks that mention a term. Each row has displayPath and firstMatch {chunkIndex, parentId, snippet, and pages in a PDF as in query_documents}, or null when only the title matched. limit (default 50, capped at 200) pages the list and nextOffset is present while more remain; the counts always cover every match. With no match, notice states the absence and what it covered. A row carries lookAlikes as in query_documents, from the whole index: check them before quoting a figure.

Only indexed text is searched: files not yet synced (list_files shows them) and images without OCR are not, and a phrase that a chunk boundary splits is not found. scope, labels, dateFrom and dateTo filter as in query_documents, and citations follow its rule: each document's displayPath, verbatim.

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": {
      "terms": "<terms>"
    },
    "name": "find_mentions"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNo
matchNoall
scopeNo
termsYes
dateToNo
labelsNo
offsetNo
dateFromNo

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.1.1

TDQS

A4.8/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: boundary matching is prefix-open (акт finds акта/актов but also актуально), quoting forces exact-word match, case/ё-е/Unicode composition are ignored, matching is literal so synonyms are separate terms, and up to 10 terms are allowed. It also discloses search coverage limits (unsynced files, non-OCR images, and chunk-split phrases are not found) and pagination behavior (default 50, cap 200, counts always cover every match).

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?

Purpose and when-to-use are front-loaded, and most sentences carry non-obvious behavioral detail that earns its place. A sizable portion, though, enumerates return fields (searchedDocuments, matchedDocuments, forms, documents, firstMatch, nextOffset, notice) that the output schema already covers, so it is denser than strictly necessary.

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 an 8-parameter, annotation-free, complex search tool, the description covers matching semantics, coverage limits, filtering, pagination, and count reliability. An agent has enough to call it correctly and to interpret results honestly, with only the four deferred filter params as a minor dependence on query_documents.

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 coverage is 0%, so the description must compensate; it explains `terms` (string or list up to 10), `match` (all vs any and what each row lists), `limit` (default 50, capped 200), and offset paging/`nextOffset`. However, `scope`, `labels`, `dateFrom`, and `dateTo` are only deferred to 'as in query_documents', so half the filters remain undocumented within this definition and require knowledge of the sibling.

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 states a specific verb and resource with scope: 'List every indexed document that mentions a word or phrase, with counts.' It immediately contrasts itself with query_documents (whole-index scan vs ranked passages), so an agent can distinguish the two 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?

Explicit trigger phrases ('which documents mention X', 'list all', 'how many', 'is X mentioned anywhere') define when to reach for this tool, and query_documents is named as the alternative with the condition that selects it. It also gives procedural guidance: check `forms` before trusting a count and check `lookAlikes` before quoting a figure.

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