> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evermuse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools reference

> Every tool the Evermuse MCP server exposes, with its parameters, annotations, permissions and results.

The Evermuse MCP server exposes **27 tools**: 22 read-only tools and 5 tools that write to your workspace. Every tool
carries a human-readable title (`annotations.title`) and the standard MCP tool annotations (`readOnlyHint`,
`destructiveHint`, `idempotentHint`, `openWorldHint`), so your client can tell reads from writes and ask for
confirmation where appropriate.

All 27 tools work on Evermuse data: each one reads or writes only the workspace you authorized, so `openWorldHint` is
`false` for all of them. The one outbound fetch is optional: when you pass a recording URL to `add_source`, Evermuse
downloads that file to process it.

## All tools

| Tool | Title | Category | Read-only | Destructive |
| - | - | - | :-: | :-: |
| [`find_skills`](#find_skills) | Find Skills | Guidance | ✓ | |
| [`read_skills`](#read_skills) | Read Skills | Guidance | ✓ | |
| [`get_products`](#get_products) | Get Products | Product context | ✓ | |
| [`get_product_summary`](#get_product_summary) | Get Product Summary | Product context | ✓ | |
| [`get_projects`](#get_projects) | Get Projects | Product context | ✓ | |
| [`customer_research`](#workflow-tools) | Customer Research | Workflow | ✓ | |
| [`competitor_analysis`](#workflow-tools) | Competitor Analysis | Workflow | ✓ | |
| [`create_prd`](#workflow-tools) | Create PRD | Workflow | ✓ | |
| [`write_brief`](#workflow-tools) | Write Brief | Workflow | ✓ | |
| [`write_feature_spec`](#workflow-tools) | Write Feature Spec | Workflow | ✓ | |
| [`user_personas`](#workflow-tools) | User Personas | Workflow | ✓ | |
| [`user_stories`](#workflow-tools) | User Stories | Workflow | ✓ | |
| [`summarize_conversation`](#workflow-tools) | Summarize Conversation | Workflow | ✓ | |
| [`search`](#search) | Search Customer Evidence | Evidence | ✓ | |
| [`view_item`](#view_item) | View Customer Evidence Item | Evidence | ✓ | |
| [`get_opportunities`](#get_opportunities) | Get Opportunities | Evidence | ✓ | |
| [`find_sources`](#find_sources) | Find Sources | Sources | ✓ | |
| [`read_source`](#read_source) | Read Source | Sources | ✓ | |
| [`list_competitors`](#list_competitors) | List Competitors | Competitors | ✓ | |
| [`get_competitor_capabilities`](#get_competitor_capabilities) | Get Competitor Capabilities | Competitors | ✓ | |
| [`get_shaping_notes`](#get_shaping_notes) | Get Shaping Notes | Shaping notes | ✓ | |
| [`read_shaping_note`](#read_shaping_note) | Read Shaping Note | Shaping notes | ✓ | |
| [`add_source`](#add_source) | Add Source to Project | Write | | |
| [`add_signals`](#add_signals) | Add Signals | Write | | |
| [`update_signals`](#update_signals) | Update Signals | Write | | ✓ |
| [`create_shaping_note`](#create_shaping_note) | Create Shaping Note | Write | | |
| [`update_shaping_note`](#update_shaping_note) | Update Shaping Note | Write | | ✓ |

Clients should call `tools/list` to see the exact tools available to a connection. `add_signals` and `update_signals`
appear only when the connection has the `mcp:write` scope, which standard OAuth connections receive by default.
`create_shaping_note`, `update_shaping_note` and the `nature` search filter are Labs features that are on by default;
a workspace admin can switch them off, and then they no longer appear.

## How the tools fit together

The server sends instructions that guide agents through a reliable research flow:

1. **Load the methodology.** `find_skills` and `read_skills` return Evermuse's research guidance (how to search, weigh
   evidence and cite it).
2. **Pick the product.** All research data belongs to a product. `get_products` lists them, and `get_product_summary`
   explains a product's goals, users and features. Pass the chosen `product_id` to every product-scoped tool.
3. **Start with a workflow tool.** For a PRD, call `create_prd`. For a research question, call `customer_research`, and
   so on. Each workflow tool returns the first round of evidence plus the methodology, next steps and quality bar for
   that task.
4. **Go deeper.** Use `search`, `view_item`, `find_sources` and `read_source` to follow up on specific evidence.
5. **Save what matters.** Optionally record new sources, signals or shaping notes with the write tools.

## Common conventions

### Common parameters

| Parameter | Type | Applies to | Description |
| - | - | - | - |
| `product_id` | string | Every product-scoped tool | The product to work in, from `get_products`. Required. An unknown id, or one from another workspace, returns an error. |
| `project_id` | string | `search`, `find_sources` and workflow tools | Narrows results to one project inside the product. Optional. Most research should run at product scope. |
| `include_guidance` | boolean | Workflow tools, `search`, `find_sources`, `find_skills`, `get_opportunities`, competitor tools | Default `true`. Attaches the relevant Evermuse skill (methodology) to the result. Set `false` once the agent already knows it, to get more data per page. |
| `workflow` | string | Most non-workflow tools | Optional label for the task the call belongs to: `customer_research`, `competitor_analysis`, `create_prd`, `write_brief`, `write_feature_spec`, `user_personas`, `user_stories`, `summarize_conversation` or `other`. Used for analytics only; it never changes results. |

### Results

* Successful results return a text content block with JSON, and the same data as `structuredContent`. Search-shaped
  tools open with a short prose **digest** (counts, date range, pagination). When guidance is attached, it comes as a
  separate text block.
* Every citable item has a `url` that links to the original evidence in the Evermuse app (for example
  `https://app.evermuse.com/s/<id>` for a signal or `/m/<id>` for a meeting). Tool descriptions ask agents to cite
  inline using those URLs and never invent links.
* Failed calls return `isError: true` with a text message such as `Error: Product not found: "abc" is not a product in
  this workspace. Call get_products …`. The message explains how to recover.
* Search-shaped tools trim each page to about 30,000 characters when guidance is attached, or about 80,000 without it,
  and report `next_offset` so the agent can continue.

***

## Guidance

### find\_skills

**Find Skills.** Hybrid keyword and semantic search over the workspace's skills library: Evermuse's built-in research
and product-management methodologies plus any custom skills your team has added. Returns skill metadata (id, title,
category, tags, description), not the full bodies. Free: doesn't use credits.

| Parameter | Type | Required | Description |
| - | - | :-: | - |
| `query` | string | ✓ | What the user wants to do, for example `"write a PRD"` or `"pricing"`. |
| `include_guidance` | boolean | | Default `true`. Also returns the full body of the best match and a context bundle: the workspace's products and the core "using Evermuse" doctrine. |
| `category` | string | | Exact category filter. |
| `tag` | string | | Tag filter. |
| `limit` | number | | Default 10, maximum 50. |

Annotations: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`.

### read\_skills

**Read Skills.** Returns the full body and references of one or more skills. Free: doesn't use credits.

| Parameter | Type | Required | Description |
| - | - | :-: | - |
| `skill_ids` | string\[] | ✓ | Skill ids from `find_skills` (up to 50). |

Annotations: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`.

***

## Product context

### get\_products

**Get Products.** Lists every product in the workspace with its id, name, tagline, description, status, platform and
segments. Call this first to choose a `product_id`. Takes no parameters except the optional `workflow`.

### get\_product\_summary

**Get Product Summary.** Returns the latest product specification: mission and vision, problem statement, user
segments, personas, and the feature inventory with statuses.

| Parameter | Type | Required | Description |
| - | - | :-: | - |
| `product_id` | string | ✓ | Product from `get_products`. |

### get\_projects

**Get Projects.** Lists the projects inside a product (`id`, `name`, `description`), or across all products.

| Parameter | Type | Required | Description |
| - | - | :-: | - |
| `product_id` | string | | Product whose projects to list. Required unless `all_products` is `true`. |
| `all_products` | boolean | | List projects for every product in the workspace. |

All three tools: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`.

***

## Workflow tools

Workflow tools are the recommended starting point for each kind of product task. Each one runs the first step of a
proven, multi-step process (a customer-evidence search, or a source lookup for `summarize_conversation`). When
`include_guidance` is `true`, it also returns the full methodology for the task: next steps, quality criteria and the
output format.

Workflow tools are **read-only**: they create and save nothing. The agent writes the PRD, brief or analysis in the
conversation. It's saved to Evermuse only if you separately ask for a write tool, such as `create_shaping_note`.

| Tool | Title | Use it to | Inputs |
| - | - | - | - |
| `customer_research` | Customer Research | Research what customers think, need, ask for or complain about. | Same as [`search`](#search) |
| `competitor_analysis` | Competitor Analysis | Analyze competitors and find openings for differentiation. | Same as [`search`](#search) |
| `create_prd` | Create PRD | Create a business PRD grounded in customer evidence. | Same as [`search`](#search) |
| `write_brief` | Write Brief | Write a brief of what was learned from customer sources in a recent time window. | Same as [`search`](#search) |
| `write_feature_spec` | Write Feature Spec | Write a testable feature specification. | Same as [`search`](#search) |
| `user_personas` | User Personas | Build evidence-backed user personas. | Same as [`search`](#search) |
| `user_stories` | User Stories | Write INVEST user stories with evidence-backed acceptance criteria. | Same as [`search`](#search) |
| `summarize_conversation` | Summarize Conversation | Summarize one meeting, call, email thread or document. | Same as [`find_sources`](#find_sources) |

All workflow tools: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`.

***

## Evidence

### search

**Search Customer Evidence.** Searches the customer evidence Evermuse has extracted from your sources: needs,
feedback, quotes, pain points, Q\&A, custom signal types, transcript sections, competitor capabilities and news. In
semantic mode every item carries an absolute `relevance` score (0–100); browse results have no score. Every item
carries a `url`.

It works in two modes:

* **Semantic search:** pass `search_query`. Results are ranked by relevance.
* **Browse:** omit `search_query` and pass at least one filter (`note_types`, `meeting_id`, `date_from` or `date_to`).
  Results are newest first.

| Parameter | Type | Required | Description |
| - | - | :-: | - |
| `product_id` | string | ✓ | Product to search. |
| `search_query` | string | | Natural-language query. Omit for browse mode. |
| `literal_user_question` | string | | The user's question, verbatim. Sharpens relevance; omit for scheduled or autonomous runs. |
| `project_id` | string | | Restrict to one project. |
| `nature` | enum | | `evidence` (direct customer signals), `context` (market, industry and competitor context and news), `guidance` (internal direction such as specs and strategy) or `all`. A Labs feature, on by default. |
| `note_types` | string\[] | | Browse mode only. `need`, `feedback`, `quote`, `problem` (pain points), `qa`, or a custom signal type name. |
| `meeting_id` | string | | Browse mode only. Signals from one meeting. |
| `date_from` / `date_to` | number | | Browse mode only. Inclusive Unix timestamps in milliseconds. |
| `customer_tags` | string\[] | | Only evidence linked to customers with any of these tags. Available when the Customers feature is enabled for your workspace. |
| `limit` | number | | Default 50, maximum 100. |
| `offset` | number | | Default 0. Use `next_offset` from the previous page. |
| `include_guidance` | boolean | | Default `true`. |

Annotations: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`.

### view\_item

**View Customer Evidence Item.** Returns the full details of one item from `search` or `get_opportunities`, including
its source and context.

| Parameter | Type | Required | Description |
| - | - | :-: | - |
| `item_id` | string | ✓ | Item id from a previous result. |
| `item_type` | string | ✓ | `need`, `problem` (or `pain_point`), `feedback`, `quote`, `opportunity`, or a custom signal type name as returned by `search`. |

Annotations: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`.

### get\_opportunities

**Get Opportunities.** Lists machine-suggested product opportunities, derived from clusters of related customer signals,
with evidence counts and, where available, the number of distinct companies behind each. Treat them as leads to
investigate, not conclusions. Use `view_item` with `item_type: "opportunity"` for details. If a product has no stored
opportunities yet, the tool returns roadmap candidates instead (marked `source: "roadmap_candidates"`), which include
their problem and solution inline.

| Parameter | Type | Required | Description |
| - | - | :-: | - |
| `product_id` | string | ✓ | Product. |
| `limit` | number | | Default 25, maximum 100. |
| `offset` | number | | Default 0. |
| `include_guidance` | boolean | | Default `true`. |

Returns `opportunities`, `total` and `next_offset` (`null` on the last page).

Annotations: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`.

***

## Sources

### find\_sources

**Find Sources.** Finds the meetings, calls, documents, spreadsheets and email or chat threads in a product. With a
`query`, results are ranked by semantic match and include the best-matching snippet. Without one, it lists sources
newest first, including those still processing.

| Parameter | Type | Required | Description |
| - | - | :-: | - |
| `product_id` | string | ✓ | Product. |
| `query` | string | | What the source is about. Omit to browse. |
| `project_id` | string | | Restrict to one project. |
| `source_types` | enum\[] | | `meeting`, `call`, `document`, `spreadsheet`, `meeting_notes`, `communication` (emails and messages). |
| `date_from` / `date_to` | number | | Unix timestamps in milliseconds. |
| `participant` | string | | A participant's name or email. A value like `@acme.com` matches a domain. |
| `attendee_email` | string | | Exact attendee email. |
| `attendee_domain` | string | | Attendee email domain. |
| `title_keyword` | string | | Keyword in the source title. |
| `include_participant_details` | boolean | | Default `false`. Adds participant ids and emails. |
| `customer_tags` | string\[] | | Available when the Customers feature is enabled for your workspace. |
| `limit` | number | | Default 20, maximum 50. |
| `offset` | number | | Default 0. |
| `include_guidance` | boolean | | Default `true`. |

Annotations: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`.

### read\_source

**Read Source.** Reads the content of one source. Meetings and calls return speaker-attributed transcript segments, and
documents and emails return titled sections. Long sources are paged.

| Parameter | Type | Required | Description |
| - | - | :-: | - |
| `source_id` | string | ✓ | Source id from `find_sources` or a search result. |
| `offset` | number | | First segment to return. Default 0. |
| `limit` | number | | Segments per page. Default 200, maximum 500. |
| `include_participant_details` | boolean | | Default `false`. |

Returns the source name and type, participants, `segments`, `total_segments`, `has_more` and `next_offset`.

Annotations: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`.

***

## Competitors

### list\_competitors

**List Competitors.** Lists the competitors Evermuse tracks for a product, with description, website, threat level,
similarity and segment.

| Parameter | Type | Required | Description |
| - | - | :-: | - |
| `product_id` | string | ✓ | Product. |
| `include_guidance` | boolean | | Default `true`. |

### get\_competitor\_capabilities

**Get Competitor Capabilities.** Returns the tracked capabilities and announcements of one competitor, with
announcement and release dates.

| Parameter | Type | Required | Description |
| - | - | :-: | - |
| `competitor_id` | string | ✓ | Competitor id from `list_competitors`. |
| `include_guidance` | boolean | | Default `true`. |

Both tools: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`.

***

## Shaping notes

Shaping notes are your team's working documents in Evermuse: collaborative markdown notes that move through a
status pipeline your workspace configures.

### get\_shaping\_notes

**Get Shaping Notes.** Lists shaping notes in a product, most recently updated first, without their content.

| Parameter | Type | Required | Description |
| - | - | :-: | - |
| `product_id` | string | ✓ | Product. |
| `keyword` | string | | Semantic search over notes. |
| `status` | string | | Status key. |
| `tag` | string | | Tag. |
| `limit` | number | | Default 50. |

Also returns the workspace's `available_statuses` and `available_tags`.

### read\_shaping\_note

**Read Shaping Note.** Returns the current version of one or more notes, with full markdown content and authorship.

| Parameter | Type | Required | Description |
| - | - | :-: | - |
| `note_ids` | string\[] | ✓ | Note ids from `get_shaping_notes`. |

Both tools: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`.

***

## Write tools

Five tools change data in your workspace. Every change is attributed to the signed-in user.

| Tool | readOnlyHint | destructiveHint | idempotentHint | openWorldHint | Permission |
| - | :-: | :-: | :-: | :-: | - |
| `add_source` | `false` | `false` | `false` | `false` | Any MCP connection |
| `add_signals` | `false` | `false` | `true` | `false` | `mcp:write` |
| `update_signals` | `false` | `true` | `false` | `false` | `mcp:write` |
| `create_shaping_note` | `false` | `false` | `false` | `false` | Any MCP connection (Labs, on by default) |
| `update_shaping_note` | `false` | `true` | `false` | `false` | Any MCP connection (Labs, on by default) |

### add\_source

**Add Source to Project.** Adds a meeting, call transcript, note, document, spreadsheet, or email or chat thread to
Evermuse, through the same processing pipeline as an upload in the app. Evermuse then extracts signals from it.

<Note>
  `add_source` returns a confirmation that the source was **queued**, not that it finished processing. Use
  `find_sources` later to see when it's ready.
</Note>

Supported shapes:

* **Note:** `content` (markdown) with `source_type` of `meeting_notes`, `call_transcription` or `document`.
* **File:** `file_base64` plus `filename` with `source_type` `document` (PDF, DOCX and other office and text formats) or `spreadsheet` (XLSX).
* **Meeting:** `source_type: "meeting"` with `transcript_turns`, `media` and/or `vendor_payload`.
* **Communication:** `source_type` of `conversation`, `message`, `email` or `email_thread`, with `messages` (preferred) or `content`.

| Parameter | Type | Required | Description |
| - | - | :-: | - |
| `source_type` | enum | ✓ | `document`, `meeting_notes`, `call_transcription`, `spreadsheet`, `meeting`, `conversation`, `message`, `email`, `email_thread`. |
| `nature` | enum | ✓ | `evidence` (direct customer input), `context` (market or competitor context) or `guidance` (internal direction). |
| `project_id` | string | | Target project. Required for notes and file uploads. |
| `product_id` | string | | Target product for imports without a project. Must match the project if both are given. |
| `title`, `subtitle` | string | | Display title and subtitle. |
| `tags` | string\[] | | Tags. |
| `content` | string | | Markdown text. Mutually exclusive with `file_base64`. |
| `file_base64` | string | | Base64-encoded file, up to about 50 MB raw. |
| `filename` | string | | Required with `file_base64`. |
| `mime_type` | string | | Must match the file extension. |
| `external_source` | string | | Origin system as a lowercase token, for example `gong`, `zoom`, `zendesk` or `slack`. |
| `external_id` | string | | Id in the origin system. Required with `external_source`. |
| `occurred_at` | string | | ISO-8601 UTC time of the conversation. Defaults to now. |
| `participants` | object\[] | | Up to 200 `{name, email?, is_internal?}`. |
| `transcript_turns` | object\[] | | Up to 5,000 `{speaker, text, start_ms?}`. |
| `media` | object | | `{url, type: "video" \| "audio", filename?, mime_type?}`. An HTTPS URL that Evermuse downloads the recording from. |
| `vendor_payload` | object | | A raw vendor export. Gong is supported. Requires `external_source`. |
| `messages` | object\[] | | Up to 2,000 `{author, text, sent_at?}`. |
| `thread_id` | string | | Thread identifier for communications. |
| `unattributed` | boolean | | Acknowledges a meeting transcript without speaker names. |

Transcript and message text is limited to 4 MB per call.

**Duplicates:** for meetings and communications, `external_source` plus `external_id` is a unique key across the
workspace. Re-submitting an existing pair returns `already_exists: true` with the existing source. It isn't processed
again, so no processing credits are used (the call itself still counts as one tool call). Notes, documents and
spreadsheets aren't de-duplicated: each call adds a new source.

### add\_signals

**Add Signals.** Records up to 100 signals (needs, feedback, quotes, pain points or your custom signal types) extracted
from an existing source. Re-sending the same signal doesn't create a duplicate: the key is source, type and content.
Requires `mcp:write`.

| Parameter | Type | Required | Description |
| - | - | :-: | - |
| `source_id` | string | ✓ | Source the signals came from (from `add_source` or `find_sources`). |
| `signals` | object\[] | ✓ | 1–100 items of `{type, content, title?, who_said_it?}`. `type` is one of your workspace's active signal types, and `content` is up to 20,000 characters. |

Returns the created signals and how many were `duplicates`.

### update\_signals

**Update Signals.** Edits up to 100 existing signals in one atomic call. Each field you pass **replaces** the stored
value, and signals have no version history, so agents should read the signal with `view_item` first. Requires
`mcp:write`.

| Parameter | Type | Required | Description |
| - | - | :-: | - |
| `updates` | object\[] | ✓ | 1–100 items of `{signal_id, title?, content?, created_at?, participant_id?, who_said_it?, signal_type_id?}`. Each item must change at least one field. |

### create\_shaping\_note

**Create Shaping Note.** Saves a new shaping note, such as a PRD or brief the agent just wrote, to a product. The note
starts its version history with this entry.

| Parameter | Type | Required | Description |
| - | - | :-: | - |
| `product_id` | string | ✓ | Product. |
| `title` | string | ✓ | Title. |
| `content` | string | ✓ | Markdown body. |
| `subtitle` | string | | Subtitle. |
| `status` | string | | A status key from your workspace's pipeline. Unknown keys return the valid list. |
| `tags` | string\[] | | Tags. |

### update\_shaping\_note

**Update Shaping Note.** Changes an existing shaping note. Only the fields you pass change, and each one replaces the
stored value. Every update adds a version-history entry, so earlier versions can be restored from the Shaping tab in
Evermuse.

| Parameter | Type | Required | Description |
| - | - | :-: | - |
| `note_id` | string | ✓ | Note to update. |
| `title` | string | | New title. |
| `subtitle` | string | | New subtitle. |
| `content` | string | | New markdown body. Replaces the whole body. |
| `status` | string | | New status key. An empty string removes the status. |
| `tags` | string\[] | | New tags. Replaces all tags. |

***

## Early-access tools

Workspaces in Evermuse's early-access programs may see additional tools in `tools/list`. The most visible is
**Create Signal Type** (`create_signal_type`), available to workspace owners and admins when custom signal types are
enabled. It prepares a draft custom signal type and shows it in an interactive review panel
(an MCP Apps UI resource, `ui://evermuse/create-signal-type`). Nothing is
created until you review the draft and click **Publish to Evermuse** in that panel. Drafts expire after 30 minutes.
Clients without MCP Apps support can't publish drafts.

## Not available over OAuth

Tools that call third-party MCP servers connected to your workspace are never exposed to OAuth connections. OAuth
connections expose Evermuse data only.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.