Skip to main content
Glama
nuncaeslupus

doc-control

by nuncaeslupus
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

find

Read-only

Search Word .docx files for text or regex patterns, returning paragraph ranges with context, totals, and a cursor for paging matches.

Instructions

Find text or a regex; matches come back as paragraph ranges, capped, with a cursor. The first page also gives total (or total_at_least and more: true when the time budget stopped the count). query_word is the query as typed in Word's Find box (^p, ^l, ^t, ^s, ^^; null past 255 characters, with ignore_accents or with a soft or no-break hyphen in the query; not for a regex; null at a folded match_level), with query_word_options (match_case, whole_words) to tick there.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
docYesPath to the .docx file.
limitNoMost matches to return; more are reached with `cursor`.
queryYesText to find (at most 1000 characters), or a Python regex if `regex`.
regexNoTreat `query` as a regex.
cursorNoThe `next` value of the previous page.
contextNoCharacters of surrounding text on each side of a match.
storiesNoStories to read (default ["body"]): "notes" adds footnotes and endnotes, each after the paragraph holding its mark; "headers" adds headers and footers, after the body. Their addresses carry a prefix (fn3/p1#…, hdr1.default/p1#…).
whole_wordNoMatch only whole words (no letter, digit or mark on either side).
ignore_caseNoIgnore case.
match_levelNoFold a literal query: `default` ignores case, accents and punctuation (symbols such as `$` still count), `loose` drops symbols too; `exact` is the search as without it. When passed, Word's Find codes (^p, ^t, ^l, ^s, ^-, ^~, ^uNNN, ^^) in `query` are read as their characters and each match gains `match_level`, the strictest level it meets. Not with `regex` (unless `exact`), nor with `ignore_case` or `ignore_accents` false at a folded level. Two meanings of exact: plain `find` (no `match_level`) matches the query as typed, flags as given, ^ codes literal, and its matches carry no level; `match_level: "exact"` keeps that text rule but reads the ^ codes and tags every match. A match's own `match_level` is `exact` only when it equals the query character for character (`case` when only case differs).
ignore_accentsNoIgnore accents: `maria` finds `María`. A regex must be written without accents then.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.5/5.0
Behavior4/5

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

Beyond the single readOnlyHint annotation, the description discloses real behavior: results are capped, paging is via cursor, the first page carries `total` or a truncated `total_at_least`/`more: true` when the time budget aborts counting, and `match_level` folding changes which matches survive. That is substantive operational context an agent could not get from the annotations alone.

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

Conciseness3/5

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

The core purpose and output shape are correctly front-loaded, but the second sentence runs long and dense with parenthetical edge cases about `query_word` nullability, soft hyphens and 255-character cutoffs. Several clauses concern fields that are not even input parameters, so the paragraph is heavier than it needs to be.

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?

With 11 parameters and no output schema, the description usefully carries the return-value story (cursor, total variants, match_level tags) that the schema cannot. It leaves usage routing and the `stories`/`context` semantics to the schema, which is acceptable given their full coverage, but the lack of any sibling differentiation is a residual gap.

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 100%, so the baseline is 3, but the description adds genuine cross-parameter meaning the schema does not: `match_level` cannot combine with `regex` (unless `exact`) or with `ignore_case`/`ignore_accents` left false at a folded level, and it disambiguates the two senses of 'exact'. It also explains the folded-level tagging semantics of a match's own `match_level`.

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

Purpose4/5

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

The opening states a specific verb and resource — find text or a regex in a document — and immediately characterizes the result shape (paragraph ranges, capped, cursor-paged). It is clear what the tool does, though it never contrasts itself with near-neighbors like `locate` or `history_search`, 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.

Usage Guidelines2/5

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

There is no explicit when-to-use or when-not guidance; the description never names an alternative tool or states the condition that selects this one over `locate`. The paging hint ('more are reached with cursor') implies the retrieval workflow but is not framed as usage direction.

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