---
name: webhound
description: Use Webhound for long-running web research reports and structured datasets. Covers when to start a report or dataset, how to use context and files, model and budget defaults, watching until done, steering active runs, retrieving sources and provenance, and diagnosing failures.
---

# Webhound Agent Skill

Use Webhound when the user needs real research, not a quick lookup.
Good fits:

- deep web research that needs many sources
- cited reports, memos, market maps, competitive scans, diligence, or briefing docs
- structured datasets with rows, fields, sources, and evidence
- follow-up work that should use prior Webhound sessions or uploaded files as context

Bad fits:

- single facts, simple definitions, or one-page summaries
- tasks the agent can answer directly without multi-source research

## Default Behavior

Prefer MCP when your client supports it. Use REST only if MCP is unavailable.
If the user says "Run Webhound onboarding" or asks to get set up, call
webhound_onboarding first. Do not inspect the local repo, search files, or read
agent memory before the onboarding tool; the tool is the source of truth for the
setup flow. After the tool returns, lead the onboarding conversation step by step
using immediate_next_message. Ask one question at a time and help the user get to
their first Webhound report or dataset run. Do not summarize onboarding as
account status; the goal is to walk the user through setup, the first run, and
workspace usage preferences.

Hosted MCP URL:

    https://api.webhound.ai/api/v2/mcp

Local stdio MCP:

    npx -y webhound-mcp

Local stdio config:

    {
      "mcpServers": {
        "webhound": {
          "command": "npx",
          "args": ["-y", "webhound-mcp"],
          "env": {
            "WEBHOUND_KEY": "wh_..."
          }
        }
      }
    }

After adding local stdio config, restart the agent session or open a new one
if Webhound tools do not appear. Many agents only load MCP servers when a
session starts.

The normal lifecycle is:

1. Choose report or dataset.
2. Start the run.
3. Watch until done is true.
4. If the run asks for input, ask the user and send the answer back.
5. After done is true, retrieve or export output, sources, claims/provenance, spend, and alerts.
6. Summarize what Webhound produced, plus explicit Webhound alerts if present.

Do not treat a long-running Webhound job as done just because it started.
The authoritative MCP completion signal is webhound_watch.done === true.
Do not treat output_ready, partial working notes, or a useful-looking draft as
completion before done is true.
Budget controls research depth. While a run is healthy and not done, Webhound
may keep searching, reading, writing, and verifying until the budget is used or
the task is naturally complete.

## Choose Report vs Dataset

Use a report when the user wants synthesis:

- explain a market, company, trend, customer segment, policy, risk, or strategy
- compare vendors or options
- produce a written answer with citations and traceable claims
- do open-ended deep research where the shape is not just rows

Use a dataset when the user wants structured rows:

- find companies, people, products, funds, customers, grants, papers, tools, or examples
- fill a schema across many entities
- enrich a list from a CSV, spreadsheet, uploaded file, or prior session
- return evidence-backed table fields instead of prose

Use prior context when it helps. Attach previous Webhound session IDs when a
new run should build on earlier output. Attach uploaded file IDs when PDFs,
CSVs, transcripts, or notes are primary source material.

Use chains only when the user explicitly wants a multi-step workflow. For most
agent use, a report or dataset is the right primitive.

## Budget

Use the Webhound default model unless the user explicitly provides a different
API-compatible model. Do not explain model/provider choices during onboarding
unless the user asks.

Budget guidance:

- $1: quick scan or small dataset
- $3: focused pass
- $5: recommended default and the free-run amount
- $10+: only when the user asks for more depth

The budget is the research allowance. More budget means more room for source
discovery, reading, writing, verification, and final assembly. The calling
agent should watch the run; Webhound decides when to finish.
Using most or all of the selected budget is expected for deep research. It is
not a sign that the agent should stop the run early.
Do not ask Webhound to finalize, wrap up, synthesize now, or stop just because
it is still running or because working notes look usable.

The free run, when available, covers exactly one private $5 report or dataset.
It is not divisible credits. Use it when the user's requested run is eligible.

Reports usually use most or all of the selected budget, then assemble the final
answer. Datasets may finish under budget if the target set is bounded and
enough rows are found.

## MCP Tool Pattern

Start:

- webhound_onboarding: first-time setup guide, defaults, free-run status, and workspace rule suggestions
- webhound_get_defaults: read saved defaults and free-run preference
- webhound_account: check credits/free-run if needed
- webhound_start_report: start a report
- webhound_start_dataset: start a dataset

Watch:

- webhound_watch: lightweight status, alerts, spend, progress, done flag
- webhound_wait: wait until done or a timeout
- If wait returns still_running, keep waiting. That is normal for budgeted research.

Steer:

- webhound_send_message: send user guidance into an active or awaiting-input run. Use it for intent changes, not normal elapsed time.
- webhound_stop: stop a run only when the user explicitly asks to stop, pause, or cancel
- webhound_resume: resume a stopped/awaiting-input run
- webhound_add_budget: add budget only after the user approves it

Read output:

- webhound_get_output: final report or dataset summary/export
- webhound_export_session: downloadable artifacts. Reports support Markdown,
  HTML, plain text, JSON traces, and PDF. Datasets support CSV, JSON, JSONL,
  Markdown, and PDF.
- webhound_get_sources: source list
- webhound_get_claims: claim/provenance data when available
- webhound_get_session: current session details
- webhound_diagnose: structured explanation when something looks wrong

Search old work:

- webhound_search_sessions: find relevant prior sessions
- webhound_list_sessions: list recent sessions

Files:

- webhound_upload_file: upload files before starting the run, then pass the
  returned file IDs into the report or dataset request.

## Watching Runs Correctly

For MCP, keep calling webhound_watch or webhound_wait until done is true.

If a healthy run is still running, it is usually spending the budget on more
research. Do not interrupt that flow unless Webhound asks for input, returns a
blocking alert, or the user changes the objective.
Warning-level tool errors during a still-running session are not by themselves
a reason to stop the run. Follow Webhound's explicit next action.

Do not read or summarize working notes mid-run unless the user explicitly asks
for a partial update. If you do give a partial update, say it is partial and
continue watching unless the user tells you to stop.

Progress updates should be short. Do not show raw status JSON, operation
counts, provisional document lists, or unfinished working-doc titles to the
user. Treat those as operational state, not final findings.

Completion reasons:

- budget_complete: run spent the intended budget and assembled output
- natural_complete: run finished before budget because the task was complete
- awaiting_input: ask the user for guidance, then send it with webhound_send_message
- user_stopped: user stopped it
- credit_exhausted: explain the credit issue and ask before adding budget
- failed: report the error and suggested recovery
- stuck_or_empty: diagnose before retrying

If the run is awaiting input, do not guess. Ask the user the specific question
Webhound needs answered.

If Webhound explicitly reports weak provenance, low source coverage, zero
dataset rows, repeated tool errors, or empty output, say that clearly. Do not
oversell the result.

## What To Return To The User

When a run finishes, provide:

- private Webhound link
- exported artifact when useful: Markdown/PDF for reports, CSV/JSON for datasets
- whether it was a report or dataset
- model and budget used
- spend and completion reason
- concise summary of the output
- source/provenance health
- explicit Webhound alerts, if present
- for datasets: row count, fill quality, duplicates if known, and export link/path
- for reports: source count and claim/provenance availability

## REST Fallback

Use REST only when MCP is unavailable.

Base URL:

    https://api.webhound.ai/api/v2

Auth header:

    Authorization: Bearer wh_...

Core fallback flow:

1. POST /research for reports, or POST /extractions for datasets.
2. Poll the session status every 10-30 seconds.
3. Read output, sources, and claims when complete.
4. On 402, tell the user they need credits or an eligible free run.
5. Do not blindly retry create requests after network errors; first check whether the session was created.