Research Toolkit

Overview Schema Source Related Servers Discussions Admin

research_save

Saves and updates research sources, claims, requirements, drafts, and briefs by stable ID in CSV/JSONL, preserving unchanged fields on partial updates and returning assigned IDs plus errors.

Instructions

Save/update source, claim and requirement objects by stable ID; the tool writes CSV/JSONL. Omitted IDs are assigned or matched by URL/claim/summary. Partial updates retain other fields and rows. requirements.unit_ids optionally assigns a requirement to named research units; omit it or use [] for global scope. work.requirement_ids selects records to read, not their applicability. All effective requirements remain accessible. sources.read_scope records actual reading; requirements.reading_requirement specifies required reading, not read_scope. For an active mandatory-reading requirement, the merged row needs reading_requirement="full_text" or "relevant_sections" and required_source_ids, a nonempty list of distinct source IDs, e.g. ["S1"]. Other requirements can omit both. IDs refer to source records; partial updates may omit fields already saved on the requirement. For local read_evidence, prefer a task-relative path to an existing nonempty file, e.g. "sources/S1.md"; put reading locations and notes in locator, e.g. "pp. 2-4; relevant sections only", not appended to the path. URL/page locators and supported local-reference forms remain valid; optional evidence_path locates local UTF-8 source text. draft uses path, optional content and complete=true for a complete draft; omit content to register an existing file. draft.main=true explicitly selects the current work; optional kind is report/comparison/review/analysis. For a contribution use kind=analysis, unit_id and the actual producing host_task; question states its research question. depends_on lists actual upstream unit IDs. complete=true records a finished unit, not an independent review or delivery; a dependent unit cannot complete before its declared upstream versions are finished and independently reviewed. Saving a prepared unit automatically retains its input versions, question and dependencies from status.work. Explicit based_on overrides that selection and copies work_context.inputs unchanged: file paths and record:sources:S1 / record:claims:C1 / record:requirements:effective or effective@unit IDs map to SHA256; copy the returned keys rather than constructing them. handoff uses summary, optional pending/decisions text lists and to (the receiving host task/session). The registered main writer transfers ownership through handoff.to; another host cannot silently replace the main draft. Saved unit originals and prior versions are retained in existing record-backups; summaries do not replace original analysis. current_work.research_outputs returns contributions, owners, current dependencies and changed inputs for research judgment. Chapter/reference drafts do not change the main selection. brief updates only supplied brief fields and task_spec together. Returns assigned IDs and field errors for the agent to resolve, without asking users to manage records. replace names complete collections to repair from recovered rows; original bytes are backed up automatically. Records reading/verification claims as supplied, never infers truth or closes requirements automatically. Saves retain event timestamps and original failures for task continuity. changes summarizes the latest record-save batch and candidate claim/report locations; identical bytes are not rewritten. Saving a source ID also compares local evidence against its previous save observation. First observations are explicit.

Input Schema

Name	Required	Description	Default
`task`	Yes
`brief`	No
`draft`	No
`claims`	No
`replace`	No
`sources`	No
`requirements`	No

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 27, 2026

addedInput schema / properties / brief

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Brief"
+}

First observedv1.1.0Oct 15, 2026

TDQS

A3.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and does so extensively: it discloses file writes, partial-update retention, automatic backups, ownership transfer through handoff.to, retention of timestamps and failures, and that claims are recorded as supplied without inferring truth. It also clarifies that requirements are not closed automatically and that identical bytes are not rewritten.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded and many sentences convey non-obvious operational rules, but the description is a dense wall of text with no headings, grouping, or examples beyond one bracketed ID example. It is information-rich rather than padded, yet the lack of structure makes it harder than necessary to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is complex, has no annotations, zero schema description coverage, and only a partial output schema, so the description needs to be rich; it covers most high-risk semantics around updates, ownership, dependencies, backups, and evidence handling. It still leaves gaps around the required task field, claims object structure, and brief fields, preventing a perfect score.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and it provides substantial meaning for nested fields such as requirements.reading_requirement, sources.read_scope, read_evidence, draft.main, based_on, depends_on, handoff, and replace. However, the required top-level task parameter is never explained, and the claims object semantics are only mentioned in passing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence clearly states a specific verb and set of resources: save/update sources, claims, and requirements by stable ID, and writes CSV/JSONL. It is broad because it also handles drafts, briefs, handoffs, and contributions, and it does not explicitly differentiate itself from siblings such as research_review or research_finish.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied throughout by detailed conditions such as 'For an active mandatory-reading requirement...' and 'For a contribution use kind=analysis...', but these are field-level rules rather than tool-selection guidance. There is no explicit statement of when to use research_save versus research_review, research_finish, or other siblings, and no when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server