Tool Catalog

The Trovella MCP server registers 18 tools organized into six categories. Every tool follows the same execution pattern: resolve organization, run inside withTenantContext, return JSON in { content: [{ type: "text", text }] } format. Tools that mutate plan or step state also call writeAuditLog() inside the transaction.

Source code: one file per tool in packages/mcp/src/tools/.

Tool Registration Order

Tools are registered in packages/mcp/src/server.ts after the withToolCallLogging middleware is applied. The ping tool is excluded from logging.

Connectivity

ping

Check that the MCP connection is working. Returns the authenticated user's name and email. Excluded from tool call logging.

Parameters: none

Returns: Connected to Trovella as {userName} ({userEmail}).

Source: packages/mcp/src/tools/ping.ts

---

Plan Lifecycle

create_research_plan

Create a new research plan with ordered steps and optional branching conditions in a single transaction. Validates that branching conditions reference valid step orders. Auto-links to an active skill_execution record if a matching sessionId is found.

Parameter	Type	Required	Description
name	string	yes	Plan name
researchQuestion	string	yes	The question to investigate
steps	array	yes	Ordered list of { stepType, instructions }
branchingConditions	array	no	{ afterStepOrder, conditionExpression, ifTrueAction, actionParams? }
sessionId	string	no	Claude Code session ID for audit tracking and skill-execution linkage
planDesignRationale	string	no	Explanation of why the plan was designed this way
outputFormattingNotes	string	no	Planning agent's initial ideas for formatting the final output

Step types: search, extract, analyze, critique, synthesize, checkpoint, custom.

Returns: { planId, name, researchQuestion, stepCount, firstStep: { stepId, stepType, instructions } }

Audit event: plan_modified with action: "created"

Source: packages/mcp/src/tools/create-research-plan.ts

get_plan_status

Return a comprehensive snapshot of plan progress including derived status, stall warnings, and step breakdowns.

Parameter	Type	Required	Description
planId	string	yes	The research plan ID

Returns: { planId, name, status, derivedStatus, stalled, progress, totalSteps, currentStep, completedSteps[], pendingSteps[] }

The derivedStatus is computed from step states via derivePlanStatus() from the plan engine. stalled uses isPlanStalled() to flag steps that have been in_progress for more than 30 minutes.

Source: packages/mcp/src/tools/get-plan-status.ts

modify_plan

Adjust a plan mid-execution. Supports five actions. Plan must be in planning or executing state.

Parameter	Type	Required	Description
planId	string	yes	The research plan ID
action	enum	yes	add_steps, remove_step, reorder_steps, update_step_instructions, fail_step
steps	array	for add_steps	Steps to add, each with optional insertAfterOrder
stepId	string	for remove_step/update_step_instructions/fail_step	Target step ID
reason	string	no (for fail_step)	Reason the step failed
stepOrder	string[]	for reorder_steps	Ordered list of step IDs
updatedInstructions	string	for update_step_instructions	New instructions text
modificationRationale	string	no	Explanation of why this modification was made
sessionId	string	no	Claude Code session ID

Action details:

• add_steps -- inserts new steps, shifting existing step orders. Each step can specify insertAfterOrder for precise placement.
• remove_step -- deletes a pending step and compacts remaining step orders. Only works on steps with pending status.
• reorder_steps -- reassigns step orders according to the provided ID sequence.
• update_step_instructions -- replaces the instructions text on an existing step.
• fail_step -- marks a pending or in-progress step as failed with an optional reason. Failed steps are treated like skipped -- the plan continues to the next step.

Audit event: plan_modified with action-specific eventData

Source: packages/mcp/src/tools/modify-plan.ts

list_active_plans

Return all non-terminal plans (not completed or failed) with progress summaries.

Parameters: none

Returns: { activePlans: number, plans: [{ planId, name, researchQuestion, status, progress, totalSteps, completedSteps, updatedAt }] }

Plans are ordered by most recently updated. Progress is calculated as (completed + skipped) / total * 100.

Source: packages/mcp/src/tools/list-active-plans.ts

---

Step Execution

get_next_step

Find the first pending step, transition it to in_progress, and ensure the plan is in executing state. If the plan was in planning or stalled, it transitions to executing.

Parameter	Type	Required	Description
planId	string	yes	The research plan ID
sessionId	string	no	Claude Code session ID

Returns one of:

Status	Meaning
next_step	{ step: { stepId, stepOrder, stepType, instructions } }
plan_complete	All steps are in terminal states. Includes outputMediaType, outputFormattingInstructions, planFormattingNotes, and stepFormattingNotes
plan_failed	Plan has been explicitly failed
awaiting_review	A step is waiting for user input
no_pending_steps	No pending steps but plan is not complete (steps are in-progress or failed)

Audit event: step_started

Source: packages/mcp/src/tools/get-next-step.ts

submit_step_result

Submit completed work for a step. Stores the result, advances the state machine, and evaluates branching conditions. Accepts both in_progress and pending steps (auto-advances pending steps to handle timing edge cases).

Parameter	Type	Required	Description
planId	string	yes	The research plan ID
stepId	string	yes	The step ID
result	object	yes	Structured result of the step
confidence	number (0-1)	no	Self-assessed confidence score
stepExecutionReport	object	no	Comprehensive execution report: thinking, web searches, tool calls
outputFormattingNotes	string	no	Formatting ideas discovered during execution
sessionId	string	no	Claude Code session ID

After storing the result, the server evaluates all branching conditions attached to this step. Conditions use simple comparison operators (e.g., confidence < 0.7). Actions: skip_to (skip intermediate steps), fail (fail the plan), continue (no-op).

Returns: { submitted: true, planStatus } -- the new plan status after branching evaluation.

Audit event: step_completed

Source: packages/mcp/src/tools/submit-step-result.ts

get_step_context

Load prior completed step results and related artifacts for reference during the current step.

Parameter	Type	Required	Description
planId	string	yes	The research plan ID
stepId	string	yes	The current step ID
priorStepIds	string[]	no	Specific steps to load (defaults to all prior completed)

Returns: { currentStep, priorSteps: [{ stepId, stepOrder, stepType, resultSummary, confidence }], artifacts[] }

When priorStepIds is omitted, loads all completed steps with stepOrder less than the current step.

Source: packages/mcp/src/tools/get-step-context.ts

---

User Interaction

request_user_review

Pause execution for human input. Transitions the step to awaiting_input and the plan to awaiting_review. Both transitions are validated before any changes are made.

Parameter	Type	Required	Description
planId	string	yes	The research plan ID
stepId	string	yes	The step requiring review
summary	string	yes	Summary of findings for the user
questions	string[]	no	Specific questions for the user
sessionId	string	no	Claude Code session ID

Audit event: user_reviewed with action: "review_requested"

Source: packages/mcp/src/tools/request-user-review.ts

submit_user_decision

Record the user's decision on a review request. The step must be in awaiting_input state.

Parameter	Type	Required	Description
planId	string	yes	The research plan ID
stepId	string	yes	The step under review
decision	enum	yes	approve, reject, modify, skip
feedback	string	no	User feedback or modification instructions
sessionId	string	no	Claude Code session ID

Decision effects:

Decision	Step Status	Plan Status	Notes
approve	completed	resumes executing	--
reject	failed	failed	Terminal for both step and plan
modify	in_progress	resumes executing	Feedback appended to step instructions
skip	skipped	resumes executing	--

Audit event: user_reviewed with decision details

Source: packages/mcp/src/tools/submit-user-decision.ts

---

Session Management

get_research_context

Load the full context of an existing research plan for cross-session resume. Returns all steps (with results), artifacts, recent audit events, linked skill execution, and output formatting preferences.

Parameter	Type	Required	Description
planId	string	yes	The plan to load
sessionId	string	no	New session ID (writes session_resumed audit entry)

Returns:

{
  plan: { id, name, researchQuestion, status, createdAt },
  steps: [{ stepId, stepOrder, stepType, status, instructions, resultSummary, confidence }],
  artifacts: [{ id, artifactType, title, confidence, stepId, createdAt }],
  recentAuditEvents: [{ eventType, eventData, stepId, createdAt }],  // last 20
  skillExecution: { id, skillName, status, metadata, durationMs, ... } | null,
  outputPreferences: { outputMediaType, outputFormattingInstructions, planFormattingNotes, stepFormattingNotes }
}

Audit event: session_resumed (when sessionId is provided)

Source: packages/mcp/src/tools/get-research-context.ts

---

Research Data

store_research

Store a completed research artifact in the research_artifact table. Triggers background indexing via emitContentCreated() when contentText is provided.

Parameter	Type	Required	Description
artifactType	enum	yes	analysis, synthesis, comparison, summary, source_list, finding
title	string	yes	Short title
content	object	yes	Structured content (shape varies by type)
contentText	string	no	Plain text for full-text search (recommended for all artifacts)
confidence	number (0-1)	no	Confidence score
planId	string	no	Link to research plan
stepId	string	no	Link to plan step

Returns: { id, artifactType, title, stored: true }

Event emitted: search/content.created (see Data & Storage -- Event Patterns)

Source: packages/mcp/src/tools/store-research.ts

search_sources

Hybrid search across all indexed research content using keyword (BM25) and semantic (vector) search, merged via Reciprocal Rank Fusion. Uses @repo/ai for query embedding and @repo/search for keyword search and RRF.

Parameter	Type	Required	Description
query	string	yes	Search query text
limit	number	no	Maximum results (1-50, default 10)
sourceTable	enum	no	research_artifact, research_output, extraction_result
artifactType	enum	no	Filter by artifact type
planId	string	no	Filter results to a specific plan

Returns: { query, queryType, resultCount, keywordResults, semanticResults, results: [{ id, sourceTable, sourceId, title, rrfScore, inKeyword, inSemantic, textSnippet }] }

The queryType field (keyword, balanced, semantic) is determined by word count heuristic via classifyQuery(). Both keyword and semantic search always run regardless of classification.

Source: packages/mcp/src/tools/search-sources.ts

extract_data

AI-powered structured extraction. Sends source text plus a JSON Schema to Claude, parses the response, computes per-field confidence, and stores results in the extraction_result table. Failed extractions return an error without creating database records.

Parameter	Type	Required	Description
sourceText	string	one required	Document text to extract from
sourceArtifactId	string	one required	Artifact ID to load text from (alternative)
extractionSchema	object	yes	JSON Schema describing what to extract
schemaVersion	number	no	Schema version (default 1)
planId	string	no	Link to research plan
stepId	string	no	Link to plan step
sourceUrl	string	no	URL of original source
sourceLocation	object	no	Location within source (page, section)

Uses createAIHelper(orgId, userId, logger) from @repo/ai with feature: "mcp-extract-data". This is one of only two tools that makes AI API calls (the other is search_sources for query embedding).

Returns: { extractionId, data, fieldConfidences, overallConfidence, status: "completed" }

Source: packages/mcp/src/tools/extract-data.ts

store_research_output

Store a research deliverable (the final output document). Supports multiple media types. Triggers background indexing when contentSummary is provided.

Parameter	Type	Required	Description
planId	string	yes	Plan this output belongs to
mediaType	enum	yes	conversation, markdown, html, word, excel, powerpoint
title	string	yes	Title of the deliverable
content	string	yes	File content (text or base64 for binary formats)
contentSummary	string	no	Brief summary for indexing and admin display
formattingNotesUsed	string	no	Summary of which formatting instructions were followed
sessionId	string	no	Claude Code session ID

Returns: { outputId, mediaType, title, stored: true }

Event emitted: search/content.created (when contentSummary is provided)

Source: packages/mcp/src/tools/store-research-output.ts

submit_subagent_report

Store a subagent's execution report as a research artifact. Used when a subagent completes work on a plan step, to persist its thinking, web searches, and tool calls.

Parameter	Type	Required	Description
planId	string	yes	Plan the subagent is working on
stepId	string	yes	Parent step the subagent is working within
description	string	yes	What the subagent was tasked to do
report	object	yes	Execution report: thinking, web searches, web fetches, tool calls
sessionId	string	no	Claude Code session ID

Stored as a research_artifact with artifactType: "analysis" and source: "subagent".

Returns: { reportId, stored: true }

Source: packages/mcp/src/tools/submit-subagent-report.ts

---

Skill Execution Tracking

log_skill_execution

Track the lifecycle of a research skill invocation. Call without executionId to create a new record; call with executionId to update an existing one.

Parameter	Type	Required	Description
executionId	string	no	Omit to create; provide to update
skillName	enum	yes	research, research-scan, research-deep
status	enum	yes	started, executing, completed, failed
planId	string	no	Research plan ID to link (set after plan creation)
metadata	object	no	Freeform debug data (detectedType, delegatedTo, stepCount, etc.)
errorMessage	string	no	Error details when status is failed
sessionId	string	no	Claude Code session ID

On creation, inserts a new skill_execution row. On update, shallow-merges metadata with existing metadata and computes durationMs for terminal states.

Returns: { executionId, skillName, status, stored: true }

Source: packages/mcp/src/tools/log-skill-execution.ts

---

Feedback

submit_research_feedback

Record user feedback about a completed research plan. Called at two moments: right after delivering results (initial) and when the conversation shifts away (closing).

Parameter	Type	Required	Description
planId	string	yes	Plan this feedback is about
feedbackType	enum	yes	initial (right after delivery) or closing (when conversation shifts)
userSatisfaction	enum	no	positive, neutral, negative, none
userFeedbackSummary	string	no	Summary of what the user said
improvementSuggestions	string	no	Specific things to do differently
followUpRequested	boolean	no	Whether the user asked for deeper investigation
followUpDetails	string	no	What deeper investigation was requested
sessionId	string	no	Claude Code session ID

Returns: { feedbackId, feedbackType, stored: true }

Source: packages/mcp/src/tools/submit-research-feedback.ts

---

Tools Not Yet Built

These tools are planned but not implemented:

Tool	Ticket	Dependency
verify_citations	TRO-60	NLI pipeline (DeBERTa)
extract_chart_data	TRO-61	Multimodal preprocessing
get_entity_graph / upsert_entities	TRO-62	Knowledge graph schema

Related Pages

• Tool Protocol Overview -- server architecture, tool file pattern, adding a new tool
• Middleware and Logging -- how tool calls are transparently logged
• Resources and Events -- MCP resources and event emission