Skip to main content
Glama

Search the text of documents

search_text
Read-onlyIdempotent

Search the text of every document postalref holds, or of one, for the pages that say the words, best first: those that say them as a phrase, then by how much of the page they are and how many of them it says side by side or close together, a table of contents last. A court's filing or a Justice Department release about a fraud case comes after USPS's own pages when one of those says every word, as Publication 52 and a release about a bulk mail fraud both say bulk mail permit; a case's name finds its records first. A document gives at most three pages while other documents' pages fill the list, and more gives each document a hit is from that has more pages with the words, and how many: search again with its id as document to rank only its pages. A page needn't have the words a question asks with, such as how, get or take. Each word is found in its forms, and a name also as the registry's other names for it, BCG for Business Customer Gateway or Post Office Box for PO Box, and a size as 4x6 or 4 x 6; a hit another wording found gives it as by. Each hit gives the id and page read_source reads, and the passage that says most of the words. Use it when no title names what you're looking for, as for a price in the Mail Classification Schedule or a rule in a DMM chapter. A hit's context is a whole sentence, list or row of the page unless it starts or ends with …: quote it with the hit's id and page, or give them to read_source as document and page for the sentences around it. When no hit answers, search again with the words an answer would say.

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

Input Schema

NameRequiredDescriptionDefault
limitNoAt most this many pages; 10 when absent.
queryYesWords a page says: a price, a rule, a size, a name. Each word is found in its forms: one or many, -ed, -ing, -able, -ous.
documentNoOnly this document's pages, by the id a hit or search_documents gives: every page of it that says the words, up to `limit`. Every held document when absent.

Output Schema

NameRequiredDescriptionDefault
hitsYes
moreNo
matchYes
queryYes
totalYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedInput schema / properties / document
      Added value: +{
      +  "description": "Only this document's pages, by the id a hit or search_documents gives: every page of it that says the words, up to `limit`. Every held document when absent.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / more
      Added value: +{
      +  "items": {
      +    "additionalProperties": true,
      +    "properties": {
      +      "id": {
      +        "type": "string"
      +      },
      +      "pages": {
      +        "maximum": 9007199254740991,
      +        "minimum": -9007199254740991,
      +        "type": "integer"
      +      }
      +    },
      +    "required": [
      +      "id",
      +      "pages"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
  2. Changed2 schema fields changed
    • changedInput schema / properties / query / description
      Previous value: -"Words a page says: a price, a rule, a size, a name. Each word is found in its forms: one or many, -ed, -ing, -able."New value: +"Words a page says: a price, a rule, a size, a name. Each word is found in its forms: one or many, -ed, -ing, -able, -ous."
    • addedOutput schema / properties / hits / items / properties / by
      Added value: +{
      +  "type": "string"
      +}
  3. Added

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already establish readOnly, idempotent, non-destructive, closed-world behavior, yet the description adds real operating detail beyond them: ranking logic (phrase matches first, then coverage and adjacency, table of contents last), a per-document cap of three pages, and the `more` field signaling further pages per document. It also discloses stemming and synonym expansion (BCG/Business Customer Gateway, 4x6/4 x 6) and a fallback strategy when nothing is found, none of which the annotations convey.

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?

Purpose and usage are front-loaded, but the body is a single dense block of run-on clauses ("how much of the page they are and how many of them it says side by side or close together") that takes effort to parse. It also spends sentences explaining hit fields such as `more`, `by`, and `context` even though an output schema exists, which is redundant with structured data.

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 search tool with an output schema, this covers everything an agent needs: ranking, caps, per-document refinement, synonym/stem behavior, hit structure, quoted-context practice, and a recovery path when nothing matches. No behavioral or procedural gap is left for the caller to infer.

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 meaning: `document` is described as restricting ranking to one document's pages, and its id comes from a hit or from search_documents. It also explains the interaction between `document` and `limit` (a single document yields at most three pages while other documents fill the list) and characterizes `query` as words like a price, rule, size, or name with morphological matching.

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 states a specific verb and resource plus scope: "Search the text of every document postalref holds, or of one, for the pages that say the words." It also distinguishes itself from the title-based sibling by saying to use it "when no title names what you're looking for," so an agent can route between search_text and search_documents.

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 when-to-use is given with concrete examples ("a price in the Mail Classification Schedule or a rule in a DMM chapter") and an explicit exclusion (not when a title already names the target). It also routes follow-up actions: re-search with a document id to rank only that document, and hand hits to read_source or read_source-style lookup with id/page for surrounding sentences.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources