MCP Tools Reference

research

Submit a deep research query. Always creates a new thread and dispatches to providers. To follow up on existing research, use follow_up instead.

Parameters

Parameter	Type	Required	Default	Description
`query`	string	Yes	--	The research question
`budgetTier`	enum	No	`"M"`	`XXS`, `XS`, `S`, `M`, `L`, `XL`
`providers`	string[]	No	auto	`perplexity`, `gemini`, `openai`, `grok`, `anthropic`
`mode`	enum	No	`"methodical"`	`fast` or `methodical`

Returns

{
  "threadId": "...",
  "jobId": "...",
  "status": "dispatched",
  "selectedProviders": ["perplexity", "gemini"],
  "budgetTier": "M",
  "estimatedDuration": "2-5 minutes",
  "message": "Research dispatched. Use research_status to check progress, then get_results when complete."
}

Errors

Error	Meaning
`INSUFFICIENT_BALANCE`	Balance too low for the selected tier. Response includes `balanceCents` and `requiredCents`.

research_status

Check the progress of a running research job, including per-provider status.

Parameters

Parameter	Type	Required	Description
`jobId`	string	Yes	Job ID from `research` tool

Returns

{
  "jobId": "...",
  "status": "running",
  "progress": {
    "perplexity": { "status": "completed", "durationSeconds": 45, "startedAt": "..." },
    "gemini": { "status": "running", "startedAt": "..." }
  },
  "providersComplete": 1,
  "providersTotal": 2,
  "elapsedMs": 48000,
  "nextStep": "1/2 providers complete. Waiting for remaining providers."
}

Errors

Error	Meaning
`JOB_NOT_FOUND`	Job does not exist or does not belong to your account.

get_results

Retrieve the synthesized results of a completed research job, including the unified report and follow-on suggestions.

Parameters

Parameter	Type	Required	Default	Description
`jobId`	string	Yes	--	Job ID
`includeProviderReports`	boolean	No	false	Include individual provider reports
`includeClaimsJson`	boolean	No	false	Include structured claims

Returns

{
  "jobId": "...",
  "status": "completed",
  "synthesis": "# Research Report\n\n...",
  "followOnSuggestions": [
    { "topic": "What are the regulatory implications?", "rationale": "..." },
    { "topic": "How do delivery mechanisms compare?", "rationale": "..." }
  ],
  "cost": {
    "totalCents": 406
  },
  "duration": {
    "totalSeconds": 187,
    "byProvider": { "perplexity": 45000, "gemini": 142000 }
  }
}

When includeProviderReports is true, the response also includes:

{
  "providerReports": {
    "perplexity": "## Perplexity Research Report\n\n...",
    "gemini": "## Gemini Research Report\n\n..."
  }
}

When includeClaimsJson is true, the response also includes the claims array from the synthesis.

Errors

Error	Meaning
`JOB_NOT_FOUND`	Job does not exist or does not belong to your account.
`JOB_NOT_COMPLETE`	Job is still running. Response includes current `status`.

follow_up

Pursue a follow-on question from a completed job's suggestions, or ask a custom follow-up in the same thread.

Parameters

Parameter	Type	Required	Default	Description
`jobId`	string	Yes	--	Parent job ID
`topicIndex`	number	No	0	Index into `followOnSuggestions`
`customQuery`	string	No	--	Custom query (overrides topicIndex)
`budgetTier`	enum	No	Parent job's tier	Budget tier for this follow-up

Returns

{
  "threadId": "...",
  "jobId": "...",
  "parentJobId": "...",
  "query": "What are the regulatory implications?",
  "status": "dispatched",
  "budgetTier": "M",
  "message": "Follow-up research dispatched. Use research_status to check progress."
}

Errors

Error	Meaning
`JOB_NOT_FOUND`	Parent job does not exist or does not belong to your account.
`THREAD_BUSY`	Thread already has research in progress. Wait for it to complete.
`INVALID_TOPIC`	No suggestion at the given index. Response includes `availableSuggestions`.
`INSUFFICIENT_BALANCE`	Balance too low for the selected tier.

list_threads

List recent research threads.

Parameters

Parameter	Type	Default	Description
`limit`	number	20	Max results (max 100)
`offset`	number	0	Pagination offset

Returns

{
  "threads": [
    {
      "id": "...",
      "title": "What are the latest advances...",
      "createdAt": "2026-03-16T10:00:00Z",
      "updatedAt": "2026-03-16T10:05:00Z"
    }
  ],
  "count": 1,
  "limit": 20,
  "offset": 0
}

get_thread

Get a specific thread with all messages, jobs (newest first), and provider steps for the most recent job.

Parameters

Parameter	Type	Required
`threadId`	string	Yes

Returns

{
  "id": "...",
  "title": "What are the latest advances...",
  "createdAt": "2026-03-16T10:00:00Z",
  "messages": [
    {
      "id": "...",
      "role": "user",
      "content": "What are the latest advances in CRISPR gene therapy?",
      "costCents": null,
      "createdAt": "2026-03-16T10:00:00Z"
    }
  ],
  "jobs": [
    {
      "id": "...",
      "status": "completed",
      "budgetTier": "M",
      "researchMode": "methodical",
      "query": "What are the latest advances in CRISPR gene therapy?",
      "synthesisMarkdown": "# CRISPR Gene Therapy...\n\n...",
      "suggestedFollowOns": ["...", "..."],
      "totalCustomerCostCents": 406,
      "durationSeconds": 187,
      "createdAt": "2026-03-16T10:00:00Z",
      "completedAt": "2026-03-16T10:03:07Z"
    }
  ],
  "steps": [
    {
      "id": "...",
      "provider": "perplexity",
      "status": "completed",
      "durationSeconds": 45
    }
  ]
}

Errors

Error	Meaning
`THREAD_NOT_FOUND`	Thread does not exist or does not belong to your account.

balance

Check credit balance and optionally view recent transactions.

Parameters

Parameter	Type	Default	Description
`includeTransactions`	boolean	false	Include recent transactions

Returns

{
  "balanceCents": 4250,
  "balanceDollars": "$42.50",
  "hasPaymentMethod": true
}

When includeTransactions is true, the response also includes:

{
  "transactions": [
    {
      "id": "...",
      "type": "credit",
      "amountCents": 2500,
      "description": "Manual top-up",
      "creditSource": "top_up",
      "createdAt": "2026-03-15T09:00:00Z"
    }
  ]
}

usage

Get usage analytics for a time period, including spend by provider and recent jobs.

Parameters

Parameter	Type	Default	Description
`period`	enum	`"30d"`	`7d`, `30d`, `90d`, `all`

Returns

{
  "period": "30d",
  "totalSpendCents": 1250,
  "totalSpendDollars": "$12.50",
  "providerBreakdown": [
    { "provider": "openai", "totalCostCents": 600, "jobCount": 3 },
    { "provider": "perplexity", "totalCostCents": 350, "jobCount": 5 }
  ],
  "recentJobs": [
    {
      "id": "...",
      "status": "completed",
      "budgetTier": "M",
      "query": "What are the latest advances in CRISPR...",
      "costCents": 406,
      "createdAt": "2026-03-16T10:00:00Z"
    }
  ]
}

list_providers

List available research providers and default provider assignments per budget tier.

Parameters

Parameter	Type	Description
`budgetTier`	enum	Optional. Filter to a specific tier's defaults.

Returns

{
  "providers": [
    {
      "name": "perplexity",
      "provider": "perplexity",
      "displayName": "Perplexity",
      "isActive": true,
      "typicalCostRange": "...",
      "strengths": ["..."]
    }
  ],
  "budgetTiers": [
    {
      "tier": "M",
      "maxCostCents": 1500,
      "maxCostDollars": "$15.00",
      "defaultProviders": ["perplexity", "gemini"]
    }
  ]
}

search_claims

Search and filter claims from completed research jobs. At least one filter (threadId, jobId, or query) is required.

Parameters

Parameter	Type	Required	Default	Description
`threadId`	string	No	--	Filter claims by thread (uses latest completed job)
`jobId`	string	No	--	Filter claims by specific job
`query`	string	No	--	Text search within claim content
`confidenceLevel`	enum	No	--	`high`, `medium`, or `low`
`limit`	number	No	20	Max results (1-100)

Returns

{
  "claims": [
    {
      "id": "...",
      "content": "Base editing efficiency exceeds 90% in recent trials",
      "confidence": 0.92,
      "confidenceLevel": "high",
      "supportingProviders": ["perplexity", "gemini"],
      "contradictingProviders": [],
      "jobId": "...",
      "createdAt": "2026-03-16T10:03:07Z"
    }
  ],
  "total": 1
}

Errors

Error	Meaning
`JOB_NOT_FOUND`	Job does not exist or does not belong to your account.
`THREAD_NOT_FOUND`	Thread does not exist or does not belong to your account.
`MISSING_FILTER`	No filter provided. Supply `threadId`, `jobId`, or `query`.

get_claim_evidence

Get the full evidence chain for a specific claim, including supporting sources, snippets, and optionally the claim's event history.

Parameters

Parameter	Type	Required	Default	Description
`claimId`	string	Yes	--	The claim ID
`includeHistory`	boolean	No	false	Include full event history

Returns

{
  "claim": {
    "id": "...",
    "content": "Base editing efficiency exceeds 90% in recent trials",
    "confidence": 0.92,
    "confidenceLevel": "high",
    "supportingProviders": ["perplexity", "gemini"],
    "contradictingProviders": []
  },
  "evidence": [
    {
      "id": "...",
      "relation": "supports",
      "snippet": "Clinical data shows base editing reached 91% efficiency...",
      "relevanceScore": 0.95,
      "discoveredByProvider": "perplexity",
      "source": {
        "url": "https://example.com/article",
        "title": "CRISPR Base Editing Advances",
        "domain": "example.com",
        "type": "article",
        "doi": null
      }
    }
  ],
  "evidenceCount": 1
}

When includeHistory is true, the response also includes:

{
  "history": [
    {
      "eventType": "claim_created",
      "actorType": "system",
      "payload": { ... },
      "createdAt": "2026-03-16T10:03:07Z"
    }
  ]
}

Errors

Error	Meaning
`CLAIM_NOT_FOUND`	Claim does not exist or does not belong to your account.

MCP Tools Reference

On this page