Skip to main content
Glama

Passage Data — cited environmental limits

Cite a public document by page

cite_document
Idempotent

A public document sent here is kept in our library, to be indexed and read into cited rows; a link on a file-sharing host or carrying a signature or token is read and never kept (kept says which, and why). Cite numbers or phrases from a public document by page: give its address (a PDF, a web page or plain text, up to 40 MiB) and what to find, as the document prints it. Each find comes back with every page it is printed on (n_hits, the first 5 with their quote), the quoted text around it, and a cite naming the page, the address, the document's sha256 and the day it was read: the citation an answer can carry. Matching is exact as typed: a number as printed (0.10 is not 0.1; a decimal comma reads as a point), spaces optional, letters in any case, µg read as ug. A find not printed on the pages read is in not_found, with any pages not read; a scan with no text layer is refused, not read by OCR. A document may print a provision twice, as it stood and as amended: say which page you quote. held_as names the instruments this server already reads rows from when the document is one of them.

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": {
      "url": "<url>",
      "find": "<find>"
    },
    "name": "cite_document"
  }
}

Input Schema

NameRequiredDescriptionDefault
urlYesThe document's public address (http or https): a regulation, a permit, a guideline, a report.
findYesWhat to cite, as the document prints it: a number with its unit (0.10 mg/L), a table or section name (Table 2, 445A.1237), a phrase.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.5/5.0
Behavior5/5

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

With annotations only covering safety flags, the description adds a great deal: documents are kept/indexed in a library while file-sharing-host or signed/token links are read but never kept (with `kept` explaining which and why), a 40 MiB size ceiling, exact-match rules (0.10 vs 0.1, decimal comma, optional spaces, case-insensitivity, µg read as ug), not-found handling, and OCR refusal for image-only scans. These are operational traits an agent cannot infer from readOnlyHint=false or openWorldHint=true.

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?

Most content earns its place, but the description opens with retention-policy detail before stating the tool's purpose, and the dense semicolon-and-backtick prose ('read into cited rows', 'names the instruments this server already reads rows from') is harder to parse than it needs to be. Front-loading the core verb-resource and simplifying the register would improve it without losing information.

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?

There is no output schema, and the description carries that burden fully: it names the return fields (`n_hits`, the first 5 `quote`s, `cite` with page/address/sha256/read date, `not_found`, `kept`, `held_as`) and covers edge cases such as unread pages and refused scans. For a two-parameter tool of this complexity, nothing essential to correct invocation is missing.

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 already 100%, so the baseline is 3, but the description adds real meaning: the `url` may be a PDF, web page, or plain text up to 40 MiB, and the `find` string must be typed as the document prints it, with the exactness rules governing how to construct it. That formatting guidance is materially useful beyond the schema's terse field docs.

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 description states a specific verb and resource: 'Cite numbers or phrases from a public document by page,' with the input (address + what to find) and output (page numbers, quotes, a `cite` with page/sha256/day) spelled out. That scope is clearly distinct from siblings like search, fetch, ask_site, or add_document, and `held_as` even marks the overlap case where another instrument-reading tool already covers the document.

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

Usage Guidelines4/5

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

It gives clear context for use (cite from a public document by page, supplying the address and the text as printed) and implicit exclusions (scans with no text layer are refused, links on file-sharing hosts or with signatures/tokens are not kept). It also warns that a provision may be printed twice and the caller must say which page is being quoted. It stops short of explicitly naming alternative sibling tools or stating when not to use this one.

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.