MCP Tools Reference

Overview

When you connect Trovella to your AI tools, your AI assistant gains access to the twelve tools listed below. These tools are called automatically by your AI assistant as needed — you don't invoke them directly.

The surface is intentionally small: each tool has a single responsibility and rejects payloads that miss its required structural fields, so the right path stays easier than the wrong one. The server's discovery instructions describe the canonical sequence (plan → cycle → gate → critique → synthesize → review) and every tool's response includes a nextRequiredCall or nextRecommendedAction pointing at what comes next.

research_plan

Start a new research plan. This is the atomic entry point — it creates the plan, persists a structured brief artifact, and scaffolds one step per phase in a single call.

Required fields:

name — short plan name.
researchQuestion — the verbatim question the plan answers.
briefTitle — title for the persisted brief artifact.
briefContent — the full structured brief. Required sub-fields: successModel (≥40 chars), audienceRegister, scope.inclusions[], outputStructure.{shape, requiredFields[]}, antiPatterns[], honestyContract[], seedEntities[], phaseSequence[] (≥1 phase with id, type, name, purpose, and round-1 iterationGateCriteria), plus either clarifyingQuestions[] (each with an answer) OR a clarifyingSkipReason (≥40 chars). validationHierarchy[] (≥3 tiers) is required when any phase has type evidence_validation.

The brief is the structural forcing function — every downstream tool reads its phaseSequence, iterationGateCriteria, validationHierarchy, antiPatterns, and outputStructure.

research_brief

Read or extend the brief for an existing plan. Composition happens atomically inside research_plan; this tool covers the post-creation lifecycle.

read — return the brief and every addendum in chronological order. Use after context compaction to re-anchor the plan's forcing function.
addendum — append a new addendum with triggerReason (iteration_gate_continue | critique_route_back | manual), triggerNote, a delta (added phase / updated criteria / scope expansion), and learnings[].

research_cycle

Close a search-analyze cycle or request an override.

close — atomic per-cycle persistence. Requires non-empty facts[], sources[], artifacts[] (≥1), and searchesPerformed[]. Multi-stat sources (≥3 numeric claims in one source) must reference a prior knowledge_extract via extractionResultId on the facts citing them, otherwise the close is rejected.
request_override — when there's genuinely no evidence to persist this cycle, submit a substantive ≥40-char reason. The server returns a decisionId; on user approval (submit_user_decision), pass it as forceOverride to a subsequent close. Single-use and time-bounded (24h).

research_gate

Evaluate iteration progress against the brief's criteria, then route the plan forward.

evaluate — return a snapshot of the current phase's roundN criteria and graph state (facts in phase, artifacts in phase, cycles closed, etc.). Judgment stays with the caller.
continue_cycle — record a brief addendum with escalated criteria for the next round and loop back to research_cycle.close.
advance_phase — move currentPhaseId to the next phase and write a phase_context artifact bridging outputs to the next phase's inputs.
proceed_to_critique — persist a critiqueFailureThreshold spec that research_critique.apply_threshold consumes mechanically.

research_critique

Run the adversarial pass on the synthesized plan.

submit — store critique findings. Requires structuralFinding (does the analysis answer the original question, and if not what's the scope gap), honestyAudit (thin-validation called out, documented harms integrated, consulting projections excluded), plus sensitivityFlags, contraryEvidenceIntegrated, overhypedVsUnderappreciated, tierDowngrades, retractions, and optional newContradictsEdges.
apply_threshold — compare findings against the most-recent gate decision's threshold spec. Returns routeDecision: return_to_search (write a brief addendum and re-open cycles) or proceed_to_synthesize.

research_synthesize

Compose the final deliverable by recombining stored artifacts and graph facts — not by re-deriving from chat context.

compose — enforces output-to-longest-artifact ratio < 5x and citation coverage (every numeric in the output needs a factId within 200 chars). Below 60% coverage blocks; 60–80% emits an advisory. Provide overrideRatioCheck: <userDecisionId> to bypass the ratio gate after user authorization.
read — fetch the most-recent composed output for a plan.

research_review

Verify the synthesized output before delivery.

trace — walk every quantitative claim, confirm each resolves to a real fact, and check that the brief's required output-structure fields are populated. Returns a per-dimension pass/fail result with specific findings.
submit — persist a review artifact recording the trace decision plus reviewer notes.

research_query

Discover plans across the workspace. Filter by status (active | completed | failed | stalled | awaiting_review | all), search plan name + research question text, paginate via limit + offset. Returns per-plan progress, step counts, artifact counts, and fact counts. Call this at the start of a research request to avoid duplicating prior work.

knowledge_query

Query the knowledge graph and stored research content. Three views:

search — hybrid keyword (BM25) + semantic (vector) search over research artifacts, outputs, and extraction results. Merged via Reciprocal Rank Fusion. Requires query; filter by sourceTable, artifactType, planId.
related — given a factId, return all SAME / SUPPORTS / MODIFIES / CONTRADICTS / SUPERSEDES edges in both directions.
cluster — given a topicId (or a factId to derive its topics), return the forest-plot data: every fact in the cluster plus typed edges between them. Heterogeneity is rendered explicitly — never averaged.

knowledge_extract

Schema-driven extraction from a raw source using AI. Provide a JSON schema describing what to pull out; Trovella runs structured AI extraction and returns the result with per-field confidence. Results are persisted in extraction_result for later reuse and can be cited by extractionResultId on facts.

This is the only tool that runs fresh AI inference on raw inputs. Call it whenever a single source carries ≥3 atomic statistics — research_cycle.close will reject otherwise.

research_feedback

Record telemetry signals.

skill_execution — track a research skill invocation lifecycle. Omit executionId to create a new record; pass it to update (upsert pattern).
user_satisfaction — capture user feedback on a completed plan. Use at two moments: initial right after delivery, and closing when the conversation shifts. Includes satisfaction level, free-text feedback, and follow-up flag.

research_retrospective

Optional post-hoc retrospective on a completed plan.

prepare — return a full plan dump + computed analytics + a structured directive for composing the retrospective.
create — store a structured retrospective with failures / whatWentWell / actionItems / trajectoryDelta and optional sections. Requires the plan to be terminal unless partial: true, and requires blamelessAcknowledgment: true.
fetch — return the retrospective plus a lean planSummary table-of-contents (default ~20–30K). Pass expand to selectively pull rows in full.
list — enumerate retrospectives on the workspace.