---
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, Hound and budget behavior, 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 once. 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, send its immediate_next_message exactly
once and present only its choices. Treat agent_playbook.conversation_flow as
the canonical sequence: the matching entry is already consumed, so after the
user replies continue with the next unconsumed entry. setup_flow is
reference-only and next_action is only the entry instruction; do not replay
them as additional sequences. Continue through the first completed Webhound
run and ask one question at a time.
Do not collapse onboarding into an account summary or a single artifact choice.
Do not repeatedly call onboarding to advance it; the returned playbook contains
the remaining steps. Continue through done=true, then return the output with
sources and provenance. If the user changes the subject, drop onboarding
immediately. Hosted clients must not create or edit workspace rules unless the
user explicitly requests that separate action.

Hosted MCP URL:

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

Local stdio MCP:

    npx -y webhound-mcp@latest

Install local stdio MCP globally/user-wide for the agent, not just inside the
current project or repository. If the client supports both global and
project-level MCP config, use the global/user config unless the user explicitly
asks for project-only setup.

Local stdio config:

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

After adding local stdio config, restart the agent session or open a new one
before trying to use Webhound. Treat that restart as part of installation:
many agents load MCP servers only when a session starts. Run webhound_health
only after the restarted or new session can see the Webhound tools.

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, then use the evidence pack: sources, claims/provenance, and working docs when depth matters.
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. Reports assemble after the
selected budget boundary. Bounded datasets may naturally complete after the
requested set has been exhausted.

## 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

Hound is Webhound's research harness, built with DeepSeek V4 Pro and GPT-5.4
across planning, execution, verification, and assembly. It is not a selectable
foundation model or mode, and it does not resolve to a single provider backend.
The user's dollar budget controls how much research effort runs. Do not ask the
user to choose a model or mode, and do not send legacy model or max-mode fields.

Budget guidance:

- $2: quick scouting (about 30 minutes)
- $5: standard and the recommended default (about 75 minutes)
- $10: deep research (about 150 minutes)
- $20: exhaustive/highest-stakes starting point (about 300 minutes or 5 hours)

As a rule of thumb, $1 buys about 15 minutes. These tiers are recommendations,
not caps or permission to spend. The user can choose a larger custom budget for
longer, deeper research; never describe $20 as the maximum.

The budget is the research allowance. More budget means more room for source
discovery, reading, writing, and verification before final assembly. The
calling agent should watch the run through the selected report budget.
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 user may explicitly revise a report budget downward. Only after that clear
request, use webhound_set_budget. If the user asks to finish with the research
already gathered, read budget_control.minimum_target_budget from watch/status
and use that amount. The revised amount becomes the report's new stopping
boundary; normal final assembly still happens after the boundary. Never lower
the budget because the agent believes enough information has already been
collected, because partial output looks good, or because the run is taking time.

The free run, when available, covers exactly one private $5 report or dataset.
It is not divisible credits. Honor the saved use_free_run_when_available
preference: use the pass automatically only when that preference is true, or
after the user explicitly consents to use it for this exact $5 run. If the
preference is false or unavailable, never infer consent.

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: rich client-aware guided first-run flow with account and included-run state, exact budget economics, setup-first versus jump-in for local agents, report/dataset selection, waiting through done=true, provenance/export, and billing follow-up
- 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
- webhound_set_budget: lower a report budget only after the user explicitly asks to reduce the remaining research scope or finish with the research already gathered

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

The final output is the synthesis entry point, not the whole information
payload. For quick summaries, final output plus sources is usually enough. For
serious follow-ups, story pitches, critique, diligence, or "dig deeper"
requests, read the full evidence pack before answering: final output, relevant
working docs, claim traces, and sources. For reports, use
webhound_export_session with select="all" and format="md" or
webhound_get_output with select="working" when you need the dense working-doc
material. For datasets, inspect rows/schema plus sources and export CSV/JSON
when the user needs to use the data elsewhere.

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: a bounded dataset exhausted the requested target set before budget
- 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
- Hound research harness 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, claim/provenance availability, and whether you read the working-doc evidence pack when the user asked for depth

## 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. If the user explicitly asks to lower a report budget, PATCH /research/:id/budget with target_budget and user_requested_budget_reduction=true.
4. Read output, sources, and claims when complete.
5. On 402, tell the user they need credits or an eligible free run.
6. Do not blindly retry create requests after network errors; first check whether the session was created.