Aggregations over the matching components
research_facetsThe cheap exploration call (2 tokens): what labels, papers, states, years and terms the matching set holds, as flat or nested (depth 2) facets; returns no hits. Example: {"query": {"filters": {"start_date": "1832-06-01", "end_date": "1832-12-31"}, "text": {"must_have_keywords": "cholera"}, "flat_facets": ["states", "month_histogram"]}}. Everything under one query key; text matching under text as strings; term_filters / any_of are lists of {"field": ..., "values": [...]} objects; an unknown key is an uncharged 422 with a hint. Facets count matches, not a ranking: anchor with must_have_phrase or must_have_keywords and filters; should_* and semantic_text only widen. At least one of flat_facets / nested_facets is required. The presets (label counts, place x era coverage, hotspots, a field census) are in research_guide section "api".
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_facets"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Aggregations only, no hits: the cheap exploration call. Facets count every MATCHING doc, not a ranking — anchor with must_have_* / phrase filters; should_have_* and semantic_text only widen the match set. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| 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. | |
| corpus | Yes | ||
| facets | Yes | ||
| total_docs | Yes | ||
| tokens_charged | Yes | What this call cost | |
| tokens_remaining | Yes | Your balance after it | |
| total_components | Yes |