Skip to main content
Glama

One page of 25 component summaries

research_search
Read-onlyIdempotent

Keyword, phrase, semantic or hybrid search with filters: one page of 25 component summaries with their lists and structured fields, never full text (1 token per page). Example: {"query": {"filters": {"start_date": "1918-09-01", "end_date": "1919-06-30"}, "text": {"must_have_keywords": "influenza", "semantic_text": "the epidemic closes schools"}, "page": 1}}. hit_shape=compact halves a page (identity + summary only). Page 1 returns a cursor; send it back with page=2..; a search stops at page 10 (narrow with research_facets); only issue browse (filters.issue_uuid, sort pages:asc, no text) pages a whole issue. Keep a hit's event_id ({uuid}_evt_N) for research_component. Caution hits carry only a description and a link while guarded=true; for research the better experience is guarded=false on every call, after asking the researcher once at the start. filters.created_after / updated_after return only what is new since your last pass.

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

Input Schema

NameRequiredDescriptionDefault
queryYesOne page of 25 hits. Each page is a metered call: narrow with /facets and filters first, then page.

Output Schema

NameRequiredDescriptionDefault
hitsYesHit objects, or CompactHit objects when hit_shape=compact
modeYesWhat matched: keywords (must_/should_ words and phrases only, BM25), semantic (semantic_text only: meaning over the embedded narrative genres), hybrid (both, fused - semantic_text has WIDENED the keyword match to similar-sounding material), none (filters only). Counts and hits are of that match, not of the topic.
pageYes
corpusYes
cursorNoPass back with page+1 (same filters/text) for a stable next page; a short opaque token, valid 2 minutes from its last use. Null when there is no next page (fewer than 25 hits, or the page cap) and, under load, when the search ran without a pagination context: narrow the search instead of paging
page_sizeNo
total_docsYesMatching event docs (before collapse)
issue_pagesNoIssue browse only (filters.issue_uuid): the page count of that issue, so a client can size the read (total_components / issue_pages) before fetching; null otherwise
tokens_chargedYesWhat this call cost
tokens_remainingYesYour balance after it
total_componentsYesDistinct components matching (approximate above 40k)

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already declare read-only, idempotent, non-destructive behavior, but the description adds metered-call cost, the 10-page search cap, cursor lifetime and expiry behavior, guarded hit handling, hit_shape byte tradeoffs, expand_events, and include_boxes. This is substantial behavioral context beyond the annotations.

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?

The description is front-loaded with purpose and operational rules, and every sentence is useful. It is dense and long, with some overlap against the already detailed schema, but it avoids filler.

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 complex nested search tool with an output schema and rich annotations, the description covers pagination, filtering, safety handling, and follow-up handoff. Nothing critical for correct invocation appears missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description still adds cross-parameter workflow meaning: a concrete example query, cursor required for page > 1, the page 10 search cap, the issue-browse exception, compact hit shape, event_id retention, and created_after/updated_after incremental use. These details go beyond the field-level schema descriptions.

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?

States a specific verb and resource: keyword, phrase, semantic or hybrid search with filters, returning one page of 25 component summaries with lists and structured fields, never full text. It also distinguishes follow-up tools by naming research_component and research_facets.

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?

Explicitly says to narrow with research_facets, use issue browse only with filters.issue_uuid plus sort=pages:asc and no text, keep event_id for research_component, and ask the researcher once before using guarded=false. It covers when to page versus when to narrow.

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