One page of 25 component summaries
research_searchKeyword, 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
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | One page of 25 hits. Each page is a metered call: narrow with /facets and filters first, then page. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| hits | Yes | Hit objects, or CompactHit objects when hit_shape=compact | |
| mode | Yes | What 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. | |
| page | Yes | ||
| corpus | Yes | ||
| cursor | No | Pass 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_size | No | ||
| total_docs | Yes | Matching event docs (before collapse) | |
| issue_pages | No | Issue 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_charged | Yes | What this call cost | |
| tokens_remaining | Yes | Your balance after it | |
| total_components | Yes | Distinct components matching (approximate above 40k) |