Parallect Deep Research Skill

You have access to Parallect.ai, a multi-provider deep research platform. It queries multiple frontier AI providers simultaneously and synthesizes their findings into a single report with cross-referenced citations, extracted claims, conflict resolution, and follow-on suggestions.

Research is asynchronous -- jobs take 30 seconds to 10+ minutes depending on mode and providers. You MUST poll for completion. Never block.

Connection

Parallect is accessed via its hosted MCP server. The connection is pre-configured through your openclaw.json skill config.

• Endpoint: https://parallect.ai/api/mcp/mcp
• Auth: Bearer token using your PARALLECT_API_KEY (par_live_*)

If tools are not available, verify the key is set in your skill env and the skill is enabled.

Gotchas

Read these first. They prevent the most common mistakes:

• Research is async. Calling research does NOT return results. It returns a jobId. You must poll research_status and then call get_results only after status is "completed".
• get_results on a running job is an error. Don't call it until research_status returns "completed". You will get JOB_NOT_COMPLETE.
• You are spending the user's money. Never submit research without discussing budget first. Even an XXS tier costs ~$1.
• Polling too fast triggers rate limits. Use exponential backoff with jitter (see Step 3). Don't poll every 5 seconds.
• Balance check before research is mandatory. If the user has no balance and no payment method, the research call will fail. Check first.
• The synthesis field is markdown. Present it as-is with citations. Don't strip the formatting.
• research always creates a new thread. Do NOT pass a threadId to the research tool. For follow-up research in the same thread, use the follow_up tool with the parent jobId. Completed research reports are immutable and must not be overwritten.
• fast mode skips synthesis. It returns a single provider's raw report with no cross-referencing or conflict resolution. Only use when the user explicitly prioritizes speed.

Available Tools

Workflow: Running Research

Step 1: Discuss budget and check balance

Before submitting ANY research:

1. Call balance to check the user's current credits and payment status.

2. Call list_providers with the anticipated budgetTier to show what providers and cost range that tier includes.

3. Discuss budget with the user, framing it in natural language:

   User says...	Map to tier	Max cost	Providers	Duration
   "quick check", "just a glance"	XXS	~$1	1 provider	~30s
   "quick look", "brief"	XS	~$2	1-2 providers	~1min
   "standard", "normal"	S	~$5	2 providers	~2min
   "thorough", "detailed"	M	~$15	3-4 providers	~5min
   "comprehensive", "deep"	L	~$30	4-5 providers	~8min
   "exhaustive", "everything"	XL	~$60	All providers	~10min

   For per-tier details, provider strengths, and selection heuristics see references/budget-tiers.md.

4. Tell the user: "Your balance is $X.XX. A [tier] research will cost up to $Y. That will query [providers]. Want to proceed?"

5. If balance is insufficient and no payment method is on file, direct them to https://parallect.ai/settings/billing before proceeding.

6. If the user set a budget preference earlier in this session, reuse it silently unless the topic warrants a different tier. Don't ask again.

Why this matters: You are spending real money on the user's behalf. The agent must never auto-submit research without first establishing budget expectations. Getting this right builds trust; getting it wrong causes bill shock and churn.

Step 2: Submit the research

Call research with:

• query: A specific, well-formed research question (see Tips below)
• budgetTier: The tier confirmed in Step 1
• mode: "methodical" (default) for multi-provider synthesis. Only use "fast" if the user explicitly wants speed over depth.
• providers: Omit to let Parallect auto-select. Only specify if the user has a strong preference for specific providers.

The research tool always creates a new thread. Do NOT attempt to pass a threadId. For follow-up research on a completed report, use the follow_up tool with the parent jobId instead.

Save the returned jobId and threadId.

Tell the user: "Research submitted to [N] providers. I'll check back on progress in about 30 seconds."

Step 3: Poll for completion (exponential backoff with jitter)

Research is asynchronous. Poll using research_status with exponential backoff. Do NOT poll at fixed intervals.

Polling schedule:

attempt = 1
base_delay = 30 seconds

while job not complete:
    wait(base_delay * (1.5 ^ (attempt - 1)) + random(0, 5 seconds))
    call research_status(jobId)
    attempt += 1

In practice this looks like:

Cap the maximum interval at 120 seconds. Never poll more frequently than every 30 seconds.

On each poll, report progress naturally:

• "1 of 3 providers finished, 2 still running..."
• "All providers done, synthesis is running now..."
• "Research complete! Let me grab the results."

Shortcut: If status is "synthesizing", it's almost done. Next check in 30 seconds.

Timeout: If the job hasn't completed after 15 minutes, inform the user: "This research is taking longer than expected. Want me to keep checking, or should we try a different approach?" Offer to:

• Keep polling (set 2-minute intervals)
• Check get_results in case partial results are available
• Start a new query with fewer providers or fast mode

Silent stall detection: If 3 consecutive polls return the exact same progress (same providers complete, same status), the job may be stuck. Inform the user and suggest starting fresh.

Step 4: Deliver results

When research_status returns "completed":

1. Call get_results with jobId.

   • Set includeProviderReports: false unless the user wants raw data.
   • Set includeClaimsJson: false unless the user wants structured claims.

2. Present findings in this order: a. Brief summary (3-5 sentences) of the key findings in your own words. Lead with the most important insight. b. Full synthesis -- share the synthesis markdown as-is. It contains inline citations and cross-references. c. Cost report -- "This research cost $X.XX across N providers (took Y minutes)." d. Balance check -- call balance and report: "Remaining balance: $X.XX." If below $5, flag it: "Heads up -- your balance is getting low."

3. If the job status is "failed", report what happened and suggest retrying with a different tier or fewer providers.

Step 5: Offer follow-ons

Results include followOnSuggestions. Present them as numbered options:

"Based on this research, here are directions we could explore next:

1. [suggestion 1]
2. [suggestion 2]
3. [suggestion 3]

Want me to research any of these, or ask your own follow-up question?"

When the user picks one:

• Use follow_up with the parent jobId and topicIndex (0-based) or customQuery for a custom question.
• Mention the estimated cost before submitting.
• Then repeat Steps 3-5.

Follow-ups run in the same thread, so providers have full context.

Cost Awareness Rules

You are spending the user's money at machine speed. Be responsible:

• NEVER auto-submit research in a new session without first establishing budget expectations. This is non-negotiable.
• Track cumulative session spend. After multiple queries, report: "We've spent $X.XX on research so far this session."
• Suggest cheaper tiers proactively. If the question is simple, say: "This seems like a quick lookup -- XXS (~$1) should be enough. Want to save money with that instead of M?"
• Confirm expensive operations. For L/XL tiers or chains of follow-ups, get explicit confirmation: "That'll be up to $60. Want to proceed?"
• Report cost after EVERY research job. Never skip the cost report.
• Alert at low balance. If balance drops below $5, mention it. If below $2, proactively warn that the next research might fail.
• Link to billing on insufficient funds. Don't just say "insufficient balance" -- give them the link: https://parallect.ai/settings/billing

Error Handling

Common errors: INSUFFICIENT_BALANCE, JOB_NOT_COMPLETE, RATE_LIMITED, PAYMENT_FAILED, JOB_NOT_FOUND, INVALID_TOPIC. See references/api-errors.md for full error codes, response fields, and recovery steps.

Tips for Quality Research Queries

A well-formed query saves money and produces better results:

• Be specific: "What are the latest Phase 3 clinical trial results for GLP-1 receptor agonists in treating NASH?" beats "GLP-1 drugs".
• Include constraints: time period, geography, industry sector, comparison criteria.
• If the user is vague, ask ONE clarifying question before spending money. "Could you narrow that down? Are you interested in [X] or [Y]?"
• Don't over-scope. If the user asks about a narrow topic, don't inflate it into a broad research question. Match the query scope to the budget tier.

Mode Selection

Use methodical unless the user explicitly asks for speed. The synthesis step is where Parallect adds the most value -- cross- referencing claims, resolving contradictions, deduplicating citations.

Session Memory

• Remember threadId and jobId from current research context.
• If the user says "the research" or "those results", use the most recent jobId. Don't ask them to repeat it.
• If they want to resume older research, call list_threads to find it, then get_thread for the full context.
• Track cumulative spend across the session as a running total.
• research creates a new thread every time. follow_up continues an existing thread. Never confuse the two -- using the wrong tool can overwrite a completed report.