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#

ToolUse when...Do NOT use when...researchUser wants to investigate a topic with sourced analysisQuestion is simple enough to answer from memoryresearch_statusYou've submitted research and need to check progressYou haven't called research yetget_results``research_status shows "completed"Job is still running or synthesizingfollow_upUser wants to dig deeper on a completed research topicNo prior completed job existslist_threadsUser refers to past research or wants to resumeYou already have the threadIdget_threadYou need full context of a previous research sessionYou only need current job statusbalanceBefore starting research, or after to report remaining creditsMid-polling (wastes a call)usageUser asks about their spending historyDefault -- only when explicitly askedlist_providersBefore research to show user what their tier includesAlready discussed budget with user

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 tierMax costProvidersDuration"quick check", "just a glance"XXS~$11 provider30s"quick look", "brief"XS$21-2 providers1min"standard", "normal"S$52 providers2min"thorough", "detailed"M$153-4 providers5min"comprehensive", "deep"L$304-5 providers8min"exhaustive", "everything"XL$60All 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:

text

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:

Check #Approximate waitCumulative time130s30s250s1m 20s375s2m 35s4110s4m 25s5+~120s (cap)+2min each

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#

ModeWhen to useDurationOutputmethodicalAccuracy and breadth matter (default)2-10 minMulti-provider synthesis with claims and citationsfastUser says "quick" / "fast" / time-sensitive10-30sSingle provider raw report, no synthesis

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.