# Research Toolkit

[![MIT License](https://img.shields.io/badge/license-MIT-596259)](./LICENSE) [![Framework checks](https://github.com/rrrrrredy/research-toolkit/actions/workflows/framework-checks.yml/badge.svg)](https://github.com/rrrrrredy/research-toolkit/actions/workflows/framework-checks.yml)

[English](./README.md) · [简体中文](./README.zh-CN.md)

**Turn a research question or existing material into a report with concrete judgments and traceable sources.**

Use it for industry research, product comparisons, company analysis and technical research. Start a new study, revise an existing report against its sources, or update conclusions when new material arrives. Your host agents research, write and independently review; Toolkit connects their methods, evidence and deliverables through one research entry and optional task tools.

[**Choose an entry**](#which-should-i-use) · [Start research](#quick-start) · [See a research case](#research-case) · [Documentation](#documentation)

## How does a study get done?

The lead agent maintains the research question, effective requirements and overall judgment. Research agents investigate, compare, calculate and write substantial parts. A designated assembling agent reads their full work and sources, reconciles the argument and develops the main report progressively. Different independent agents review it, audit the findings and accept the final version.

| Responsibility | How the work connects |
| --- | --- |
| Task and context | Keep the current brief, outline, effective requirements and dependencies together. Satisfied requirements remain visible when they still constrain later work. |
| Evidence and analysis | Give each researcher a bounded question, relevant original material and related findings. Preserve its evidence, reasoning, conditions and unresolved questions in the handoff. |
| Writing and revision | Develop meaningful research units, review premises before dependent work, and integrate their complete analysis into one owned main draft. Changes return to affected units and the outline. |
| Review and delivery | Complete seven separate content-review perspectives, relevant domain review, independent audit and final acceptance against the current report and sources. Resolve necessary corrections before delivery. |

These are four connected responsibilities, not four fixed agents or four independent pipelines. Codex, Claude Code and similar hosts run the agents and carry messages; Toolkit provides shared inputs, methods, artifact relationships and completion checks. Host-native collaboration does not require separate API setup. [Research steps](docs/quickstart.md#research-from-scratch) · [Handoff and calls](docs/usage-modes.md#research-delegation-and-handoff)

```mermaid
flowchart LR
  L[Lead: question and outline] --> R[Research agents: evidence and arguments]
  R --> W[Designated assembling agent: progressive main draft]
  R --> U[Independent review at important dependencies]
  U --> R
  W --> V[Seven content perspectives + domain review]
  V --> A[Independent audit]
  A --> F[Independent final acceptance]
  A -->|Necessary correction| R
  F --> D[Complete report]
```

## Which should I use?

**The Skill provides research methods, CLI and MCP expose the same local tools, and the plugin bundles the Skill with MCP.** These are not four research methods or separate choices for briefs, long reports or research depth.

| Your situation | What to use or install | How to start |
| --- | --- | --- |
| You want your existing agent to follow the research methods | **Skill**: read the repository directly without installation, or install the Skill for repeated use. No Python or MCP required. | Send the request below; the agent reads methods as needed and uses its existing research and writing capabilities. |
| You want methods and task tools together, and your host supports plugins | **Plugin**: installs the Skill and MCP together; local tools need Python 3.10+ and MCP dependencies. | Follow the [plugin instructions](./docs/usage-modes.md#install-the-plugin), reopen the session, select Toolkit and describe the research. |
| You need saved task state, recovery and links between sources and drafts, and your host supports local MCP | **MCP**: configure the local service and use the same Skill for methods. No separate MCP setup is needed if the plugin already supplies it. | Follow the [MCP setup](./docs/usage-modes.md#connect-mcp-separately); the agent calls `research_*` tools. |
| You work in a terminal or script, or your host has no MCP support | **CLI**: download the repository and use Python 3.10+; no MCP dependencies needed. | The agent reads the same Skill and invokes the same task tools through the [command line](./docs/usage-modes.md#skill-only-and-cli-fallback). |

For a first use, start directly with the Skill. Add task tools when persistent state, tool-managed reviews or delivery checks help the work, not because a report reaches a word count. You do not need to install all four or use them in sequence. Skill-only use supports in-depth long reports without requiring the tools' CSV/JSONL registries or delivery receipts.

**Which tasks fit?** Industry, company, technology and policy research requiring multiple sources, comparison, explanation or supported recommendations; long reports, revisions and continuing updates. A one-page selection brief can need these methods too. Simple factual questions, routine translation or minor wording edits usually need only your existing agent. Toolkit does not supply a search service or replace the agent's access to and reading of sources.

[Research from scratch](./docs/quickstart.md#research-from-scratch) · [Revise or update a report](./docs/quickstart.md#revise-or-update-a-report) · [Install for your host](./agents/README.md#choose-your-tool)

<a id="usage"></a>

## Quick start

Describe your question or requested revision in your own words to an agent that can read the repository and sources. The example below is a starting point; you do not need to fill in undecided details. The agent uses existing context to propose an approach and clarifies only consequential gaps. No installation is needed to use the methods directly.

```text
Use Research Toolkit: https://github.com/rrrrrredy/research-toolkit
Read SKILL.md and follow the methods needed for this task.

I want to understand or resolve: [The question, or what to change in an existing report.]
Audience and purpose: [Who will read it and why, if known.]
Material and explicit requirements: [Sources, scope, cutoff, format or length, if available.]

Deliver a complete report that answers these questions with usable citations;
include a short change note when revising.
```

[**Start research: one usage guide**](./docs/quickstart.md)

One method set supports long-form and in-depth research, revisions and updates. The request determines scope, length and depth; the agents load methods for their current work and complete independent review, audit and acceptance.

**Only need to review an existing report?** Use the standalone [Research Review](https://github.com/rrrrrredy/research-review) Skill. Toolkit already includes these review capabilities; existing users do not need a second installation.

Have a draft or new material? [Revise or update existing research](./docs/usage-modes.md#continue-existing-research), reusing completed research and its sources.

## Research case

<a href="https://github.com/rrrrrredy/research-toolkit/blob/main/docs/case-study/api-or-browser/report.md">
<picture>
  <source media="(prefers-color-scheme: dark) and (max-width: 600px)" srcset="./docs/assets/api-browser-case.en.mobile.dark.png">
  <source media="(max-width: 600px)" srcset="./docs/assets/api-browser-case.en.mobile.png">
  <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/api-browser-case.en.dark.png">
  <img src="./docs/assets/api-browser-case.en.png" alt="APIs or browsers for AI agents. Original English research: choose an execution route by action coverage, verified completion, and recovery." width="840">
</picture>
</a>

**APIs or browsers for AI agents.** An English report drawing on 11 primary sources to compare API calls, DOM automation and visual interaction through completion, recovery and cost.

[**Read the report**](./docs/case-study/api-or-browser/report.md) · [Initial draft](./docs/case-study/api-or-browser/initial.md) · [Sources](./docs/case-study/api-or-browser/sources.md) · [Reviews and revisions](./docs/case-study/api-or-browser/reviews.md)

<details open>
<summary><strong>A revision that changes the decision</strong></summary>

**Before:**
> There is no benefit in preserving this split if the API later covers document generation with adequate permissions and result checking.

**After:**
> If the API later covers document generation with adequate permissions and result checking, the original coverage gap disappears. Retiring the browser step then depends on whether the expected maintenance and recovery savings justify migration and revalidation costs.

The review identified a missing counterexample: replacing a working browser step may cost more than the expected savings. The revision makes that trade-off part of the recommendation.

[Explore the revision](https://rrrrrredy.github.io/research-toolkit/?lang=en&case=migration&detail=reason#case)

</details>

Public-source analysis dated 10 October 2026, not a deployment test. Also read the [Chinese office-agent comparison](./docs/case-study/report.zh-CN.md) and its [source and revision archive](./docs/case-study/office-agents/README.md).

<a id="use-as-an-mcp-server"></a>
<a id="review-and-acceptance"></a>
<a id="inside-the-toolkit"></a>

## Agent setup

| How you want to use it | Entry |
| --- | --- |
| Read the methods directly | Send the request above; for files or text-only chats, see [agent setup](./agents/README.md#use-without-installation). |
| Install a Skill or plugin | [Choose your agent](./agents/README.md#choose-your-tool) · [Plugin installation](./docs/usage-modes.md#install-the-plugin) |
| Save progress and call workflow tools | [MCP installation and client configuration](./docs/usage-modes.md#connect-mcp-separately) · [CLI](./docs/usage-modes.md#skill-only-and-cli-fallback) |
| Try the local tools | [Runnable MCP example and captured responses](./examples/mcp/README.md); synthetic examples explain the interface, while real execution records retain their actual review scope. |

Nine local tools provide shared task context, on-demand methods, source and analysis saving, registered release-log queries, reviews and delivery checks. CLI and MCP use the same implementation. MCP requires Python 3.10+ and a client that can launch local processes; setup covers Windows, macOS and Linux.

Independent review uses fresh host contexts. Each required perspective has its own reviewer; authors and assembling agents do not review their own work. Audit and final acceptance have separate assignments. CLI/MCP retains the original host responses and input versions through the same `research_review` operation. [Review and acceptance](./docs/review-completion.md)

<a id="evaluation-suite"></a>
<a id="evaluation-results"></a>

## Evidence and evaluations

Public records include complete reports, original failures, reviews and repairs. They show concrete report corrections and tested workflow behavior; they do not yet establish a general quality or efficiency advantage over a native agent. Case studies, model comparisons and software checks answer different questions.

[Current evidence and limits](./docs/evaluation-status.md) · [Complete-report version comparison](./evals/studies/2026-10-13-before-after/README.zh-CN.md) (Chinese) · [Datasets and checks](./evals/README.md) · [Historical data archive](https://github.com/rrrrrredy/agent-trajectory-data/blob/main/docs/PUBLIC-EVALUATIONS.md)

## Documentation

| Need | Entry |
| --- | --- |
| Research and writing methods | [Research guide](./docs/research-guide.md) · [Skill instructions](./SKILL.md) |
| Delegate research and integrate results | [Collaboration and requests](./docs/usage-modes.md#research-delegation-and-handoff) · [Research production and handoff](./references/subagents-and-review-loop.md#research-production-and-handoff) |
| Existing reports and source updates | [Continue existing research](./docs/usage-modes.md#continue-existing-research) |
| Installation and configuration | [Agent setup](./agents/README.md) · [Usage guide](./docs/usage-modes.md) |
| Development and changes | [Contributing](./CONTRIBUTING.md) · [Changelog](./CHANGELOG.md) |

[All documentation](./docs/README.md) · [Website](https://rrrrrredy.github.io/research-toolkit/) · [Submit a failure case](https://github.com/rrrrrredy/research-toolkit/issues/new?template=failure-case.yml)