@deepseek-ai/dsh-tool-research

@deepseek-ai/dsh-tool-research

English | 中文

Model-facing research tools for the lead agent. All writes go through ctx.research's immutable append path.

Tools

• research_delegate — records one evidence duty as research/assignment-created + research/route-decided on the calling session and executes it end-to-end: the child runs through the runtime-subagent path on the routed profile's provider/model, and the produced evidence event is appended to the session. The recorded expectedSchema/authority come from the runtime's own role registry. Optional routing signals (uncertaintySignals, disagreementCount, locatorAvailable, deterministicVerificationAvailable) shape the routed profile and verification level. Roles: scout, bibliographic-verifier, extractor, claim-verifier, citation-auditor, adjudicator.
• research_propose_decision — records a PROVISIONAL conclusion (research/decision-proposed, status always provisional). The lead may propose, never approve: every supportingClaimId must be isEligibleForSynthesis (verified, supporting, above the confidence floor), else the proposal is refused and nothing is recorded. Approval and rejection belong to the human-adjudication path.
• research_ledger_query — projects the Evidence Ledger and returns one slice as JSON text: papers, claims, decisions, objections, synthesis-eligible claims, or decisions that may be presented for human approval (respecting open objections and a decisionId filter).
• research_request_approval — presents one eligible provisional decision to a human through the approval seam and records the human's verdict (never the agent's). The decision must be presentable (not settled, not already awaiting a human, no unresolved objections), else the request is refused and nothing is recorded. On allowed-once it appends research/human-decision-recorded (approved) + research/run-settled (approved); on rejected the rejected counterparts; on cancelled/unavailable it appends nothing further and returns awaiting_human. Requires the @deepseek-ai/dsh-user-approval package composed.
• research_link_fulltext — links retrieved, hashed full text to a paper already in the ledger, appending research/fulltext-linked (which sets the paper to fulltext_retrieved in the fold). Refuses unknown paper ids and records nothing.

The lead composes these to run the evidence pipeline: delegate evidence work, query the ledger, propose provisional conclusions, request human approval, and link retrieved full text.

Model Experience

The five research tools

What the model sees

The lead agent sees five tools on ctx.tools: research_delegate (delegate one evidence duty to a research subagent and execute it end-to-end, returning the run id, assignment id, route, escalation flag, and produced result), research_propose_decision (record a PROVISIONAL conclusion — the lead may propose, never approve or reject; approval and rejection belong to the human-adjudication path), research_ledger_query (project the Evidence Ledger and return one slice as JSON text), research_request_approval (present one eligible provisional decision for HUMAN approval and record the human's verdict through the approval seam), and research_link_fulltext (link retrieved, hashed full text to a paper).

Token effect

Each visible tool adds a fixed schema to the request, and tool-call arguments plus the rendered results stay in conversation history.

KV Cache effect

Prefix-stable while the tool definitions and visibility are unchanged; new calls and results extend the conversation normally.

Known Limitations and Deferred Work

• Routing signals are model-supplied, not ledger-derived — research_delegate accepts uncertaintySignals, disagreementCount, locatorAvailable, and deterministicVerificationAvailable as tool arguments, but the lead must self-report them; the tool does not yet derive disagreement or uncertainty automatically from the ledger.
• Budget context is a size-based estimate — observed usage is charged as child-prompt bytes plus produced-result bytes to the routed tier (a strong-tier run charges strong-model tokens; anything else charges agent tokens), not real provider counts; exact counts are unreachable until the settled SubagentResult carries a usage field (upstream blocker), so the budget the router reads is indicative, not exact.
• research_request_approval requires @deepseek-ai/dsh-user-approval composed — without the approval package the tool throws (rather than fabricate a verdict) and leaves the decision awaiting_human; a composed answerer that fails closed yields 'unavailable' and the same awaiting_human return.

Source: packages/research/dsh-tool-research/src/index.ts