MCP tool reference

Every tool, every argument, and what each one returns.

This page is generated from the same tool definitions the server sends to clients, so it cannot drift from what is actually exposed. If a tool appears here, tools/list returns it.

Every tool is read-only. See connecting a client for configuration and rate limits.

`search_claims`

Search evidence-graded claims extracted from research papers. Filter by direction, outcome category, evidence grade, paper type, and effect type. Returns claims with nested paper context and relationship counts.

Argument	Type	Required	Notes
`direction`	`string`	no	Effect direction: positive, negative, mixed, or null_result. One of: `mixed`, `negative`, `null_result`, `positive`
`effect_type`	`string`	no	Quantitative effect measure type. One of: `cohens_d`, `count`, `dollars`, `log_points`, `odds_ratio`, `other`, `percentage`, `standard_deviations`
`evidence_grade`	`string`	no	Evidence grade: high, medium, low, or speculative. One of: `high`, `low`, `medium`, `speculative`
`limit`	`integer`	no	Max results (1–50, default 20). Default: `20`
`min_evidence_weight`	`number`	no	Minimum composite evidence weight (0.0–1.0).
`outcome_category`	`string`	no	Canonical outcome category name (e.g. 'developer_productivity').
`paper_type`	`string`	no	Study design type. One of: `commentary`, `correlational`, `descriptive`, `other`, `quasi_experimental`, `rct`, `review_meta`, `theoretical`
`query`	`string`	no	Full-text search over claim text.

`search_papers`

Hybrid search over research papers by title, author, DOI/URL, subject/theme, abstract/summary, and claims. Returns structured paper metadata with scores, matched fields, snippets, and provenance.

Argument	Type	Required	Notes
`author`	`string`	no	Best-effort filter over normalized author names.
`evidence_strength`	`string`	no	Evidence strength filter. One of: `high`, `medium`, `low`
`limit`	`integer`	no	Max results (1–50, default 20). Default: `20`
`methods_rigor`	`string`	no	Methods rigor filter. One of: `high`, `medium`, `low`
`min_relevance`	`integer`	no	Minimum relevance score (1–10).
`paper_type`	`string`	no	Study design type. One of: `commentary`, `correlational`, `descriptive`, `other`, `quasi_experimental`, `rct`, `review_meta`, `theoretical`
`query`	`string`	no	Natural-language, title, author, DOI, URL, or subject query.
`source`	`string`	no	Paper source filter, e.g. arxiv, openalex, semantic_scholar.
`theme`	`string`	no	Research theme to filter by. One of: `adoption`, `governance`, `human_ai_collab`, `inequality`, `innovation`, `labor_markets`, `org_design`, `productivity`, `skills_training`
`year_from`	`integer`	no	Earliest publication year to include.
`year_to`	`integer`	no	Latest publication year to include.

`find_authors`

Find authors/researchers by name. Uses researcher entities when available and falls back to normalized paper author strings.

Argument	Type	Required	Notes
`limit`	`integer`	no	Max authors (1-50, default 20). Default: `20`
`query`	`string`	no	Author name or partial name.

`get_author_papers`

Return papers for an author by author_id from find_authors or by author_name. Results use the same structured shape as search_papers.

Argument	Type	Required	Notes
`author_id`	`string`	no	Author id returned by find_authors, e.g. entity:123.
`author_name`	`string`	no	Author name to match against paper author strings.
`limit`	`integer`	no	Max papers (1-50, default 20). Default: `20`

`semantic_search`

Semantic vector search over papers (via text chunks) or claims. Requires embeddings to be pre-computed. Falls back gracefully when no vectors are indexed.

Argument	Type	Required	Notes
`limit`	`integer`	no	Max results (1–20, default 10). Default: `10`
`query`	`string`	yes	Natural language query to embed and search.
`search_type`	`string`	no	Search over paper chunks or claims (default: papers). One of: `papers`, `claims` Default: `papers`

`get_paper`

Retrieve full details for a single paper by paper_id. Returns paper metadata, methodological assessment, all extracted claims with their cross-paper relationships, and linked HuggingFace resources.

Argument	Type	Required	Notes
`paper_id`	`string`	yes	Unique paper identifier (e.g. 'arxiv:2401.12345' or 'openalex:W123').

`list_digests`

List available weekly digest dates, sorted newest first.

Argument	Type	Required	Notes
`limit`	`integer`	no	Maximum number of digests to return (1-50, default 10) Default: `10`

`get_digest`

Get the raw markdown content of a weekly digest by date.

Argument	Type	Required	Notes
`date`	`string`	yes	Digest date in YYYY-MM-DD format

How results and errors come back

A successful call returns an MCP content array with one text block. The text is a JSON document, so a client that wants structured data should parse it:

{
  "content": [
    { "type": "text", "text": "{\"results\": [ ... ], \"total\": 42}" }
  ]
}

A tool that cannot answer, because an argument is invalid or a paper does not exist, returns isError: true with a readable explanation rather than a transport failure. Your assistant sees the message and can correct itself and retry:

{
  "isError": true,
  "content": [
    { "type": "text", "text": "Invalid direction 'sideways'. Must be one of: ..." }
  ]
}

Transport-level problems are different, and use HTTP status codes: 401 for a bad credential, 429 when a budget is exhausted, 400 for a body that is not a usable JSON-RPC request. Unknown JSON-RPC methods return -32601 with HTTP 200, as the protocol requires.

One tool costs money

semantic_search computes an embedding for your query on every call, which is a paid request to a model provider. It is metered far more tightly than the others and has a daily ceiling per key. The other tools only read the local corpus.

If keyword search will answer the question, prefer search_papers or search_claims. Reach for semantic_search when the phrasing in the query is unlikely to match the phrasing in the corpus.