Skip to main content
Glama
Sign In

Lawstronaut

by com.lawstronaut
OverviewDiscussionsAdmin

search

Read-onlyIdempotent

Searches legal documents using OpenSearch to discover relevant documents based on the supplied search criteria. Returns matching documents and their available metadata.

When to use: Use when you need to discover relevant legal documents through search, especially when looking for documents matching a search query rather than retrieving a structured list. Use this to explore legal content relevant to a topic, legal issue, phrase, or other supported search criteria. When not: Do not use this to browse with structured filters and cursor pagination; use list_documents. Do not use it to read a body or a file. For plain text use list_full_text (example: 'quote the operative wording'). For structured Markdown use list_markdown (example: 'keep the article headings'). For a complete citation bundle use evidence_pull (example: 'show me the source'). For a temporary source-file URL use document_presigned_url (example: 'download the PDF'). For one historical version use document_version. Do not call without a valid iso from list_jurisdictions. Avoid repeating an equivalent search when you already have sufficient results for the same query and filters.

Parameters: iso (required) is the jurisdiction code from list_jurisdictions (e.g. BE or US_CA for a state). Provide the search query and any supported optional filters defined by the input schema. Optional filters may narrow the search by document metadata, dates, authority, source identifiers, tags, or other supported criteria. Use only parameters defined by the schema. The results depend on the query, jurisdiction, filters, and the user's subscription access. An empty data array means no matching documents were returned; it does not necessarily mean that the jurisdiction has no documents.

Behavior: Read-only search operation. Does not create, update, or delete documents, records, files, or credentials. The primary side effect is the computational and resource cost of executing an OpenSearch query. Auth: tools/call requires OAuth 2.0 or a Bearer token (401 if missing, invalid, revoked, or no active subscription). Rate limits: none at the MCP layer; safe to retry. Search results are determined by the OpenSearch query implementation, relevance logic, supported filters, and available indexed data. Results may not include every document in the jurisdiction. Search results may differ from list_documents because the tools use different retrieval mechanisms. Repeating a search executes another query. Do not assume results are cached or that the search index contains every recently updated document.

Returns: Matching legal documents and their available metadata, together with a result message. The returned documents depend on the search query, jurisdiction, supported filters, and subscription permissions.

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": {
      "iso": "<iso>"
    },
    "name": "search"
  }
}

Input Schema

NameRequiredDescriptionDefault
isoYesFilter by Jurisdiction ISO code (e.g. 'US')
tagNoFilter by tag
urlNoFilter by document URL
langNoExact portal language name, for example English. Filters the portal, not the document language.
uuidNoFilter by UUID. Leave blank to apply no UUID filter.
limitNoPage size. Default 20, maximum 100.
portalNoFilter by portal name
statusNoFilter by document status
keywordNoSearch text matched against the heading and the body. Example: '29 CFR 825.500 retention period'. Omit it to list by filters only, newest document id first.
next_idNodocument id of the first row of the next page, from pagination.next_id. Omit on the first page.
versionNoFilter by version
portal_idNoFilter by portal ID
is_repealedNoFilter by repealed documents. default value is false
last_updatedNoYYYY-MM-DD, or a range YYYY-MM-DD-to-YYYY-MM-DD. Leave blank to apply no date filter.
crawling_dateNoYYYY-MM-DD, or a range YYYY-MM-DD-to-YYYY-MM-DD. Leave blank to apply no date filter.
include_totalNoInclude total count in response
effective_dateNoYYYY-MM-DD, or a range YYYY-MM-DD-to-YYYY-MM-DD. Leave blank to apply no date filter.
file_data_onlyNoFilter by file data only
last_amendmentNoYYYY-MM-DD, or a range YYYY-MM-DD-to-YYYY-MM-DD. Leave blank to apply no date filter.
expiration_dateNoYYYY-MM-DD, or a range YYYY-MM-DD-to-YYYY-MM-DD. Leave blank to apply no date filter.
date_of_decisionNoYYYY-MM-DD, or a range YYYY-MM-DD-to-YYYY-MM-DD. Leave blank to apply no date filter.
publication_dateNoYYYY-MM-DD, or a range YYYY-MM-DD-to-YYYY-MM-DD. Leave blank to apply no date filter.
date_of_enactmentNoYYYY-MM-DD, or a range YYYY-MM-DD-to-YYYY-MM-DD. Leave blank to apply no date filter.
issuing_authorityNoFilter by issuing authority
source_identifierNoFilter by source identifier
type_of_authorityNoFilter by type of authority
issuing_authority_tagsNoFilter by issuing authority tags
source_secondary_identifierNoFilter by secondary source identifier

Output Schema

NameRequiredDescriptionDefault
dataYesDocuments in the requested jurisdiction that have crawled links; empty if none match.
messageYesResult message
paginationNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedOutput schema / properties / data / items / properties / summary
      Added value: +{
+  "description": "Summary",
+  "type": [
+    "string",
+    "null"
+  ]
+}
    • changedOutput schema / properties / data / items / required
      Previous value: -[
-  "id",
-  "uuid",
-  "version",
-  "title",
-  "section_title",
-  "language",
-  "is_repealed",
-  "jurisdiction",
-  "source",
-  "classification",
-  "dates",
-  "content",
-  "provenance"
-]New value: +[
+  "id",
+  "uuid",
+  "version",
+  "title",
+  "section_title",
+  "language",
+  "is_repealed",
+  "summary",
+  "jurisdiction",
+  "source",
+  "classification",
+  "dates",
+  "content",
+  "provenance"
+]
  2. Added

TDQS

A4.7/5.0
Behavior5/5

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

Goes well beyond the supplied annotations: it discloses OAuth 2.0/Bearer auth with 401 behavior, no MCP-layer rate limits and retry safety, the real cost being an OpenSearch query, absence of caching, and that the index may miss recently updated documents. It also explains that an empty data array means no matches, not that the jurisdiction lacks documents, which is exactly the kind of inference an agent would otherwise get wrong.

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?

Section labels (When to use / When not / Parameters / Behavior / Auth / Rate limits / Returns) make it skimmable and the purpose is front-loaded. However, the "Returns" section largely restates the opening sentence, and the dependency of results on query/jurisdiction/filters/subscription is asserted three separate times, so the length is not fully earned.

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 28-parameter search tool with an output schema, the description covers everything an agent needs before calling: required jurisdiction provenance, that only schema-defined parameters are valid, auth and retry posture, result-set limitations, and how results differ from list_documents. Return value shape is correctly left to the output schema rather than duplicated.

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; the description still adds provenance for the only required parameter (iso must come from list_jurisdictions, with a US_CA state-code example) and groups the optional filters into meaningful families (metadata, dates, authority, source identifiers, tags). It does not add format detail for individual filters, but the schema already carries that.

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 resource ("Searches legal documents using OpenSearch") plus the scope of what is returned (matching documents and metadata). It explicitly contrasts itself with list_documents and with the reader/export siblings, so an agent can place it in the toolset without opening schemas.

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?

Provides an explicit "When to use" and "When not" block, and routes each excluded case to the correct alternative (list_documents for filter browsing, list_full_text, list_markdown, evidence_pull, document_presigned_url, document_version). It also adds a precondition (valid iso from list_jurisdictions) and an anti-pattern (repeating an equivalent search once results are sufficient).

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

All Lawstronaut toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources