Tool reference

Describe your task and name the project for project operations. Organization model tools act on the connected organization and need no project argument. See Projects and permissions for access levels.

Projects and knowledge

Tool	What it does
`connection_profile`	Identify the connected Sovara account and organization.
`list_projects`	List available projects and the assistant’s access to each.
`create_project`	Create a project with Admin access. Hosted connections require Allow project creation.
`get_project`	Look up a project’s name, ID, and access level.
`search`	Find relevant published lessons across readable projects.
`fetch`	Read the full lesson selected from search results.

Reading requires Read access. See Knowledge and citations for search and retrieval behavior.

Project tools

Choose the project by name or ID. The assistant’s access must meet the level shown below. Changes to lesson configuration require Admin, and comment editing follows Sovara’s normal ownership permissions.

Runs and annotations

Tool	Minimum access	Behavior
`list_runs`	Read	Find recorded runs with filters and pagination.
`probe`	Read	Inspect a run’s steps, input, output, or a step range.
`step_overview`	Read	Summarize an LLM step using the Fast Helper Model; may consume model usage. Use `probe` for tool or MCP steps.
`run_logs`	Read	Read the persisted log for one run.
`list_tags`	Read	List the project’s run tags.
`create_tag`	Write	Create a named, colored project tag.
`delete_tag`	Write	Delete a project tag and remove its assignments.
`set_run_tags`	Write	Replace a run’s tags; an empty list clears them.
`list_annotation_queue`	Read	List runs waiting for annotation with filters and pagination.
`list_annotated_runs`	Read	List annotated runs with filters and pagination.
`inspect_annotation`	Read	Inspect run annotations and analysis.
`annotate`	Write	Set a run’s saved annotation; may trigger background model analysis.
`unannotate`	Write	Clear a run’s saved annotation; may trigger model analysis of dependent runs.
`analyze`	Write	Analyze a run using configured models.
`rerun`	Write	Rerun a recorded LLM step with edited input.

Automations

Tool	Minimum access	Behavior
`list_automations`	Read	List schedules, with name and enabled/paused filters.
`get_automation`	Read	Read a schedule, its instructions, and current revision.
`automation_reasoning_options`	Read	List thinking levels supported by the configured model.
`create_automation`	Write	Create a scheduled automation.
`update_automation`	Write	Edit instructions or schedule; pause or resume.
`delete_automation`	Write	Delete an automation.
`run_automation`	Write	Queue an immediate execution.
`list_automation_executions`	Read	List one automation’s executions and statuses.
`list_recent_automation_runs`	Read	List recent started executions across the project.
`get_automation_execution`	Read	Read an execution’s configuration, output, status, and error code.

Lessons and workspaces

Tool	Minimum access	Behavior
`list_lessons`	Read	Browse lesson folders and summaries.
`get_lesson`	Read	Read one production lesson.
`retrieve`	Read	Retrieve relevant production lessons for a context in this project.
`lesson_workspace`	Read	Read published lessons or a proposal workspace.
`lesson_history`	Read	Read production lesson history.
`create_lesson`	Write	Propose a new lesson.
`update_lesson`	Write	Propose an edit to a lesson.
`create_folder`	Write	Create a lesson folder in a proposal.
`move_lessons`	Write	Move lessons or folders in a proposal.
`copy_lessons`	Write	Copy lessons or folders in a proposal.
`remove_lessons`	Write	Propose removing lessons or folders; applying publishes the change.

Proposals

Tool	Minimum access	Behavior
`list_proposals`	Read	List lesson proposals.
`get_proposal`	Read	Inspect a proposal and its diff.
`create_proposal`	Write	Create a lesson proposal.
`rename_proposal`	Write	Rename a proposal.
`proposal_conflicts`	Read	Inspect merge conflicts with production.
`resolve_proposal`	Write	Resolve conflicts between a proposal and published lessons.
`review_proposal`	Write	Request a model-generated proposal review.
`apply_proposal`	Write	Apply a proposal to publish its changes.
`close_proposal`	Write	Close an open proposal.
`reopen_proposal`	Write	Reopen a closed proposal.
`proposal_timeline`	Read	Read proposal changes, reviews, and production-application events.
`proposal_comments`	Read	Read a proposal’s comments.
`add_proposal_comment`	Write	Comment on a proposal.
`edit_proposal_comment`	Write	Edit a proposal comment.
`delete_proposal_comment`	Write	Delete a proposal comment.

Issues and conversations

Tool	Minimum access	Behavior
`list_issues`	Read	List project issues and conversations.
`get_issue`	Read	Read a numbered project issue or conversation.
`create_issue`	Write	Create a project issue.
`comment_on_issue`	Write	Add an issue comment.
`update_issue`	Write	Update or close a project issue.

Lesson proposal workflow

Lesson edits are saved in proposals. Proposal saved means a draft is ready for review; Proposal applied means its changes are published.

Ask the assistant to propose a change.
Open the proposal link and review or revise it.
Apply it in Sovara or ask the assistant to apply it.

If published lessons have changed, resolve conflicts before applying. Lesson configuration changes require Admin access.

Organize runs with tags

Tag colors: #0969da (default blue), #1a7f37, #cf222e, #bf8700, #8250df, #e85aad, #0598d5, #d1570a, #5e60ce, and #1b8a72. Assigning tags replaces a run’s full tag list. Include existing tags you want to keep; an empty list clears them. Deleting a tag removes it from every run using it.

Automations

Describe the schedule, timezone, and task. Automations are enabled by default; ask for a paused automation if you want to review it first. Automations continue after the chat ends or the MCP connection is disconnected. Pause or delete them to stop future scheduled work. Executions use your configured models and consume model usage. Each execution runs as a Sovara agent with editor access to the selected project. It can inspect project data, create and edit lesson proposals, and work with files in a persistent sandbox workspace shared by that automation’s executions. Applying a proposal to production always requires approval from a human project editor. Other actions, including setting or removing run annotations and closing issues, use the agent’s approval policy. Automations also receive the project’s enabled external MCP tools. Those tools use their configured credentials and can read or change external services; automation access is therefore not limited to Sovara lessons and runs. Changing an automation’s prompt can change how it uses these capabilities. Its data is sent to the configured model providers during execution.

Organization models

These tools act on the connected organization, without a project argument. See permissions for role requirements.

Tool	Purpose
`get_org_model_settings`	Read settings, revision, credential presence, and indexing status; optionally filter by `tier`.
`get_org_model_catalog`	List models, provider requirements, and presets.
`discover_org_local_models`	Discover models at an endpoint reachable from the server.
`set_org_model_settings`	Save tier configurations and credentials atomically.
`verify_org_models`	Test `body.tiers`; return `all_verified` and per-tier outcomes.

Pass update fields in body. Read settings before a write and pass revision as body.expected_revision. See Organization models for configuration fields, credential deletion, verification costs, and embedding-reindex confirmation. Secrets supplied through MCP may enter the host’s history. Use the CLI or Sovara settings to enter them outside the host.

Shared chat operations

Sovara chat uses the same names as MCP for shared actions: annotate, unannotate, analyze, rerun, create_lesson, update_lesson, create_folder, move_lessons, copy_lessons, remove_lessons, close_proposal, reopen_proposal, and apply_proposal. Annotation inputs use groundtruth and steps (visible references such as 2 or 3.1) across chat, MCP, and CLI. In the CLI these are --groundtruth and --steps; inspect a run with probe to find references. The shared annotation service resolves these references to stored step IDs. Surface-specific tools keep their separate purposes. Chat’s read_proposal and post_proposal_review let the agent read revision-bound review material and post its own verdict. MCP’s review_proposal starts a model review job, corresponding to CLI lessons proposals review. Chat’s edit_lesson_in_editor edits an unsaved working copy; update_lesson saves proposal changes.

Get started

Use MCP

Help

Tool reference

Projects and knowledge

Project tools

Runs and annotations

Automations

Lessons and workspaces

Proposals

Issues and conversations

Lesson proposal workflow

Organize runs with tags

Automations

Organization models

Shared chat operations

​Projects and knowledge

​Project tools

​Runs and annotations

​Automations

​Lessons and workspaces

​Proposals

​Issues and conversations

​Lesson proposal workflow

​Organize runs with tags

​Automations

​Organization models

​Shared chat operations

Projects and knowledge

Project tools

Runs and annotations

Automations

Lessons and workspaces

Proposals

Issues and conversations

Lesson proposal workflow

Organize runs with tags

Automations

Organization models

Shared chat operations