MCP Tools Reference
Complete reference for every tool available through Trovella's MCP server.
Overview
When you connect Trovella to your AI tools, your AI assistant gains access to the tools listed below. These tools are called automatically by your AI assistant as needed — you don't invoke them directly.
This reference is organized by what the tools do: creating research plans, executing steps, interacting with results, and managing data.
Plan Lifecycle
create_research_plan
Creates a new research plan with ordered steps. Your AI assistant designs the plan based on your research question, then calls this tool to register it.
- name — a short title for the plan
- researchQuestion — the question you want investigated
- steps — ordered list of tasks, each with a type (search, extract, analyze, critique, synthesize, checkpoint, or custom) and instructions
- branchingConditions (optional) — rules that adjust the plan mid-execution, such as "if confidence is low after the critique step, add more search steps"
Returns the plan ID and the first step to execute.
get_plan_status
Returns a snapshot of a plan's progress: how many steps are complete, which step is active, overall percentage, and whether the plan has stalled (no activity for 30+ minutes).
modify_plan
Adjusts a plan while it's running. Can add new steps, remove pending steps, reorder steps, update a step's instructions, or mark a step as failed. Only works on plans that are still in progress.
list_active_plans
Lists all plans that are currently in progress (not yet completed or failed). Useful for resuming interrupted research in a new session.
Step Execution
get_next_step
Pulls the next pending step from a plan and marks it as in progress. Returns the step's type and instructions so the AI assistant knows what to do. If all steps are complete, returns a "plan complete" signal.
submit_step_result
Submits the completed work for a step. Includes the structured result, an optional confidence score (0-1), and an execution report describing what the AI assistant did. After submission, the plan engine evaluates any branching conditions and advances to the next step.
get_step_context
Loads the results from previously completed steps and any stored artifacts. The AI assistant calls this before executing a step so it can build on earlier findings rather than starting from scratch.
User Interaction
request_user_review
Pauses the plan and asks for your input. Used at checkpoint steps to present findings and ask whether you want to continue, adjust direction, or stop. Your AI assistant shows you a summary and any specific questions.
submit_user_decision
Records your response to a review request. Four options:
- approve — continue with the current plan
- modify — provide feedback that adjusts the next steps (your feedback is appended to the step's instructions)
- skip — skip this checkpoint and continue
- reject — stop the plan entirely
Research Data
store_research
Stores a research artifact (analysis, synthesis, comparison, summary, finding, or source list) for future reference. Stored artifacts are automatically indexed for hybrid search so you can find them later.
search_sources
Searches your stored research using hybrid search (keyword + semantic). You can filter by artifact type, source table, or specific plan. Returns ranked results combining both search methods.
extract_data
Extracts structured data from text using AI. You provide a JSON schema describing what you want extracted, and Trovella returns the data with per-field confidence scores. Useful for pulling structured information out of unstructured research findings.
Output and Tracking
store_research_output
Stores the final deliverable from a research plan. Supports multiple formats: conversation transcript, Markdown, HTML, Word, Excel, or PowerPoint. The output is linked to its source plan for traceability.
submit_research_feedback
Records your satisfaction with a research plan's results. Called twice: once when results are first delivered ("initial") and once when you're done reviewing ("closing"). Captures satisfaction level, free-text feedback, and whether you want follow-up research.
submit_subagent_report
Stores a report from a background worker (subagent) that contributed to a step. Used when the AI assistant parallelizes work across multiple agents during a research step.
log_skill_execution
Tracks the lifecycle of a research skill invocation (started → executing → completed/failed). Links the skill execution to a plan for end-to-end traceability in the admin dashboard.
ping
Health check. Returns a confirmation message with your name and email to verify the MCP connection is working.