> For the complete documentation index, see [llms.txt](https://www.conserver.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.conserver.io/mcp-server/tool-reference.md).

# Tool Reference

Every tool, resource and prompt the vCon MCP server exposes, with the key parameters of each, so you can pick the right call without reading the source.

The server exposes 46 tools in seven groups, 7 concrete resources, 16 resource templates and 10 prompts. This page is built from each tool's `inputSchema` in [vcon-dev/vcon-mcp](https://github.com/vcon-dev/vcon-mcp) at release 1.10.0. For the response shape of a contract or search tool, call `describe_response_shape` against the live server; see [Contract Tools](/mcp-server/contract-tools.md).

Which tools a client sees depends on the deployment. `MCP_TOOLS_PROFILE`, the category variables and read-only keys filter the list; see [Transport and Deployment](/mcp-server/transport-and-deployment.md#which-tools-a-client-sees). The category in brackets after each group heading is the one those filters use.

## vCon CRUD (17 tools)

Create, read, update and delete a vCon and its parts. Category `write`, except `get_vcon` (`read`).

| Tool                        | Key parameters                                                                                                                                       | What it does                                                                                                                                                                                                                                                                              |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `create_vcon`               | `parties` (required), `subject`, `dialog`, `analysis`, `attachments`, `extensions`, `critical`                                                       | Validates and stores a new vCon. `must_support` is accepted as a deprecated alias for `critical`. The response carries `warnings`, a list of strings that flags a missing or incomplete `lawful_basis` attachment. Warnings never block the write and the server adds no basis of its own |
| `create_vcon_from_template` | `template_name` (required: `phone_call`, `chat_conversation`, `email_thread`, `video_meeting`, `custom`), `parties` (required, non-empty), `subject` | Builds a vCon from a named template and stores it. The response carries `warnings`, as for `create_vcon`                                                                                                                                                                                  |
| `get_vcon`                  | `uuid` (required), `response_format` (`full` default, `summary`, `metadata`)                                                                         | Returns one vCon. `summary` keeps only analyses of type `summary`. LLM clients should prefer `vcon_fetch`                                                                                                                                                                                 |
| `update_vcon`               | `uuid`, `updates` (both required), `return_updated` (default true)                                                                                   | Updates top-level `subject`, `extensions` and `critical` only, all inside `updates`. `must_support` is accepted there as an alias for `critical`; `critical` wins if both are sent. Use the child tools for everything else                                                               |
| `delete_vcon`               | `uuid` (required)                                                                                                                                    | Deletes the vCon and its parties, dialog, analysis and attachments. No confirmation parameter; it cannot be undone                                                                                                                                                                        |
| `add_dialog`                | `vcon_uuid`, `dialog` (both required; `dialog.type` required)                                                                                        | Appends a dialog: `recording`, `text`, `transfer` or `incomplete`                                                                                                                                                                                                                         |
| `add_analysis`              | `vcon_uuid`, `analysis` (both required; `analysis.type` and `analysis.vendor` required)                                                              | Appends an analysis                                                                                                                                                                                                                                                                       |
| `add_attachment`            | `vcon_uuid`, `attachment` (both required)                                                                                                            | Appends an attachment. Set `purpose`; `type` is a legacy field kept for old data                                                                                                                                                                                                          |
| `update_dialog`             | `vcon_uuid`, `index`, `dialog`                                                                                                                       | Replaces the dialog at `index`. Omitted fields are cleared                                                                                                                                                                                                                                |
| `remove_dialog`             | `vcon_uuid`, `index`                                                                                                                                 | Strips the dialog to a placeholder that keeps `type`, so later indexes do not shift                                                                                                                                                                                                       |
| `update_analysis`           | `vcon_uuid`, `index`, `analysis`                                                                                                                     | Replaces the analysis at `index`. `vendor` required                                                                                                                                                                                                                                       |
| `remove_analysis`           | `vcon_uuid`, `index`                                                                                                                                 | Deletes the analysis and renumbers the rest                                                                                                                                                                                                                                               |
| `update_attachment`         | `vcon_uuid`, `index`, `attachment`                                                                                                                   | Replaces the attachment at `index`                                                                                                                                                                                                                                                        |
| `remove_attachment`         | `vcon_uuid`, `index`                                                                                                                                 | Deletes the attachment and renumbers the rest. Removing the `tags` attachment clears the vCon's tags                                                                                                                                                                                      |
| `add_party`                 | `vcon_uuid`, `party`                                                                                                                                 | Appends a party and returns its index                                                                                                                                                                                                                                                     |
| `update_party`              | `vcon_uuid`, `index`, `party`                                                                                                                        | Replaces the party at `index`                                                                                                                                                                                                                                                             |
| `remove_party`              | `vcon_uuid`, `index`, `anonymize` (default false)                                                                                                    | Leaves an empty placeholder party, or `{name: "anonymous"}` with `anonymize`, so dialog and attachment references do not shift                                                                                                                                                            |

Every write is validated before it reaches the database: at least one party, and each party with an identifier; a valid dialog type; `disposition` on an `incomplete` dialog; `vendor` on every analysis; encodings of `base64url`, `json` or `none`; either `body` and `encoding` or `url` and `content_hash`; ISO 8601 dates. An analysis that uses `schema_version` instead of `schema` is rejected. Bad input comes back as an MCP `InvalidParams` error, not an internal error.

## Contract and discovery (7 tools)

The surface built for LLM clients: one envelope, cursor pagination, a byte budget. Category `read`. Design and envelopes are on [Contract Tools](/mcp-server/contract-tools.md).

| Tool                      | Key parameters                                                                                                                                                                                                              | What it does                                                                                                                                                                       |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `vcon_capabilities`       | none                                                                                                                                                                                                                        | Supported tools, include groups, search modes, limits, byte budgets and the legacy-to-contract tool mapping                                                                        |
| `vcon_taxonomy`           | none                                                                                                                                                                                                                        | Fixed guidance on tag and attachment conventions for one dealer-call dataset, plus a coverage snapshot. Disabled under the `public` profile                                        |
| `vcon_graph_shape`        | none                                                                                                                                                                                                                        | Analysis types, attachment purposes and tag keys actually present, with counts and co-occurrence edges. Same payload as resource `vcon://v1/graph/shape`                           |
| `describe_response_shape` | `tool_name`, `include_example` (default true)                                                                                                                                                                               | JSON Schema and an example payload for a contract tool or a legacy read tool. No `tool_name` lists the tools it can describe                                                       |
| `vcon_fetch`              | `id` (required), `include`, `max_response_bytes` (default 250000, min 1024)                                                                                                                                                 | One vCon in `{ok, item}` with only the include groups you ask for                                                                                                                  |
| `vcon_search`             | `mode` (`metadata` default, `keyword`, `semantic`, `hybrid`), `query`, `embedding`, `tags`, `filters`, `include`, `limit` (default 25, max 100), `cursor`, `max_response_bytes`, `threshold` (0.7), `semantic_weight` (0.6) | All four search modes behind one `{ok, items, page}` envelope                                                                                                                      |
| `vcon_aggregate`          | `group_by` (only `dealer`), `tags`, `filters.start_date`, `filters.end_date`, `having.min_count` (default 1), `limit` (default 20, max 500)                                                                                 | Per-dealer `filtered_count` and `baseline_count`, so a client can compute a rate in one call. Needs the `aggregate_vcons_by_dealer_stats` RPC. Disabled under the `public` profile |

## Search, legacy (4 tools)

The original search tools. Still supported. New clients should use `vcon_search`. Category `read`.

| Tool                    | Key parameters                                                                                                                                                                                     | What it does                                              |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `search_vcons`          | `subject`, `party_name`, `party_email`, `party_tel`, `start_date`, `end_date`, `tags`, `limit` (default 10, max 1000), `response_format` (`metadata` default, `full`, `ids_only`), `include_count` | Metadata filters only                                     |
| `search_vcons_content`  | `query` (required), dates, `tags`, `limit` (default 50), `response_format` (`snippets` default, `full`, `metadata`, `ids_only`), `include_count`                                                   | Keyword search over subject, parties, dialog and analysis |
| `search_vcons_semantic` | `query` or `embedding` (384 numbers), `tags`, `threshold` (default 0.7; 0 is honoured), `limit` (default 50), `response_format` (`metadata` default, `ids_only`, `full`)                           | Similarity search over stored embeddings                  |
| `search_vcons_hybrid`   | `query` (required), `embedding`, `tags`, `semantic_weight` (default 0.6; 0 is honoured), `limit` (default 50), `response_format` (`metadata` default, `ids_only`, `full`)                          | Keyword and semantic scores blended by `semantic_weight`  |

Keyword search is Postgres full text search (`tsvector` and `plainto_tsquery`). It stems, so "refunds" matches "refund", and it does not correct misspellings. Semantic search embeds the query with the provider set by `EMBEDDING_PROVIDER` (see [Transport and Deployment](/mcp-server/transport-and-deployment.md#semantic-search)) and compares it with the 384-dimension vectors in `vcon_embeddings`. A vCon with no embedding yet cannot be found this way.

## Tags (5 tools)

A vCon's tags live in one attachment with `purpose: "tags"`, `encoding: "json"` and a body that is an array of `"key:value"` strings, for example `["department:sales", "priority:high"]`. The materialized view `vcon_tags_mv` turns them into rows so tag filters are cheap. There is no tool that tags many vCons in one call.

| Tool              | Key parameters                                                                                                           | What it does                                                               | Category |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | -------- |
| `manage_tag`      | `vcon_uuid`, `action` (`set` or `remove`), `key` (all required), `value` (string, number or boolean; stored as a string) | Sets or removes one tag on one vCon                                        | `write`  |
| `remove_all_tags` | `vcon_uuid`                                                                                                              | Clears every tag on one vCon                                               | `write`  |
| `get_tags`        | `vcon_uuid` (required), `key`, `default_value`                                                                           | All tags on a vCon, or one tag's value                                     | `read`   |
| `get_unique_tags` | `include_counts`, `key_filter`, `min_count` (default 1)                                                                  | Distinct tag keys and values across the store                              | `read`   |
| `search_by_tags`  | `tags` (required), `limit` (default 50), `return_full_vcons`, `max_full_vcons` (default 20)                              | UUIDs of vCons that carry every given tag, optionally the vCons themselves | `read`   |

## Analytics (6 tools)

Reports over the whole store. Category `analytics`.

| Tool                           | Key parameters                                                                                                                                                          | What it does                                                                                            |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `get_database_analytics`       | `include_growth_trends`, `include_content_analytics`, `include_attachment_stats`, `include_tag_analytics`, `include_health_metrics`, `months_back` (default 12)         | One combined report                                                                                     |
| `get_monthly_growth_analytics` | `months_back` (default 12), `include_projections`, `granularity` (`monthly` default, `weekly`, `daily`)                                                                 | Ingestion over time                                                                                     |
| `get_attachment_analytics`     | `include_size_distribution`, `include_type_breakdown`, `include_temporal_patterns`, `top_n_types` (default 10)                                                          | Attachment types, media types and sizes                                                                 |
| `get_tag_analytics`            | `include_frequency_analysis`, `include_value_distribution`, `include_temporal_trends`, `top_n_keys` (default 20), `min_usage_count`                                     | Tag key and value frequencies                                                                           |
| `get_content_analytics`        | `start_date`, `end_date`, `include_dialog_analysis`, `include_analysis_breakdown`, `include_party_patterns`, `include_conversation_metrics`, `include_temporal_content` | Dialog types, analysis types and vendors, party patterns, counts of vCons with no dialog or no analysis |
| `get_database_health_metrics`  | `include_performance_metrics`, `include_storage_efficiency`, `include_index_health`, `include_connection_metrics`, `include_recommendations`                            | Performance, storage, index and cache indicators with recommendations                                   |

## Database inspection (5 tools)

For operators. Category `infra`.

| Tool                      | Key parameters                                                                                                                                          | What it does                                                         |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `get_database_shape`      | `include_counts`, `include_sizes`, `include_indexes` (all default true), `include_columns` (default false)                                              | Tables, row counts, sizes and indexes                                |
| `get_database_stats`      | `include_query_stats`, `include_index_usage`, `include_cache_stats`, `table_name`                                                                       | Table access, index usage and cache hit ratios                       |
| `get_database_size_info`  | `include_recommendations` (default true)                                                                                                                | Store size with suggested query limits                               |
| `get_smart_search_limits` | `query_type` (required: `basic`, `content`, `semantic`, `hybrid`, `analytics`), `estimated_result_size` (`small`, `medium`, `large`, `unknown` default) | A suggested result limit for a planned query                         |
| `analyze_query`           | `query` (required, SQL starting with `SELECT`), `analyze_mode` (`explain` default, `explain_analyze`)                                                   | Postgres plan for the caller's SQL. `explain_analyze` runs the query |

## Schema and examples (2 tools)

Category `schema`.

| Tool           | Key parameters                                                                                                                   | What it does                                 |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| `get_schema`   | `format` (`json_schema` default, `typescript`)                                                                                   | The vCon schema the server validates against |
| `get_examples` | `example_type` (required: `minimal`, `phone_call`, `chat`, `email`, `video`, `full_featured`), `format` (`json` default, `yaml`) | An example vCon                              |

## Resources

Read-only data at `vcon://v1/` URIs. Resource reads run no plugin hooks.

`resources/list` returns the 7 concrete URIs: `vcons/recent`, `vcons/recent/ids`, `vcons/ids`, the three `discovery/` URIs and `graph/shape`. The 16 parameterised forms below are served by `resources/templates/list` as RFC 6570 templates, so a client that only calls `resources/list` does not see them.

| URI                                                                                       | Returns                                                                                                                                                                                                               |
| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `vcon://v1/vcons/recent`, `.../recent/{n}`                                                | The newest vCons in full, 10 by default, at most 100                                                                                                                                                                  |
| `vcon://v1/vcons/recent/ids`, `.../recent/ids/{n}`                                        | UUID, timestamp and subject of the newest vCons                                                                                                                                                                       |
| `vcon://v1/vcons/ids`, `.../ids/{limit}`, `.../ids/{limit}/after/{cursor}`                | Every vCon ID, newest first, 100 by default, at most 1000. `next_cursor` is `<created_at>,<uuid>`; pass it back unchanged (URL-encoded) as `{cursor}` for the strictly older rows. A bare timestamp is still accepted |
| `vcon://v1/vcons/{uuid}`                                                                  | One vCon                                                                                                                                                                                                              |
| `vcon://v1/vcons/{uuid}/metadata`, `/parties`, `/dialog`, `/analysis`, `/attachments`     | One part of a vCon                                                                                                                                                                                                    |
| `vcon://v1/vcons/{uuid}/attachments/purpose/{purpose}`                                    | Attachments with that purpose                                                                                                                                                                                         |
| `vcon://v1/vcons/{uuid}/attachments/type/{type}`                                          | Attachments with that legacy type                                                                                                                                                                                     |
| `vcon://v1/vcons/{uuid}/analysis/type/{type}`                                             | Analyses of that type                                                                                                                                                                                                 |
| `vcon://v1/vcons/{uuid}/transcript`, `/summary`, `/tags`                                  | The transcript analysis, the summary analysis, the parsed tags                                                                                                                                                        |
| `vcon://v1/discovery/attachments/purposes`, `.../attachments/types`, `.../analysis/types` | Distinct attachment purposes, legacy attachment types and analysis types in the store                                                                                                                                 |
| `vcon://v1/graph/shape`                                                                   | The same shape graph `vcon_graph_shape` returns                                                                                                                                                                       |

## Prompts

Prompts are query templates a client can offer its user. Each returns guidance on which tools to call with which arguments. They are filtered by the same profile as the tools.

| Prompt                       | Arguments                          |
| ---------------------------- | ---------------------------------- |
| `find_by_exact_tags`         | `tag_criteria`, `date_range`       |
| `find_by_semantic_search`    | `search_description`, `date_range` |
| `find_by_keywords`           | `keywords`, `filters`              |
| `find_recent_by_topic`       | `topic`, `timeframe`               |
| `find_by_party`              | `party_identifier`, `date_range`   |
| `discover_available_tags`    | `tag_category`                     |
| `complex_search`             | `search_criteria`                  |
| `find_similar_conversations` | `reference`, `limit`               |
| `daily_activity_report`      | `date`, `focus_areas`              |
| `help_me_search`             | `what_you_want`                    |

## Which search tool

| Situation                                             | Use                                            |
| ----------------------------------------------------- | ---------------------------------------------- |
| LLM client that needs stable envelopes and pagination | `vcon_search`                                  |
| A literal word or phrase                              | `vcon_search` mode `keyword`                   |
| A concept, phrased however                            | `vcon_search` mode `semantic`                  |
| Unsure which                                          | `vcon_search` mode `hybrid`                    |
| Dates, subject, participant                           | `vcon_search` mode `metadata`                  |
| One known UUID                                        | `vcon_fetch`                                   |
| Tags only                                             | `vcon_search` with `tags`, or `search_by_tags` |
| A count or rate per dealer                            | `vcon_aggregate`                               |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.conserver.io/mcp-server/tool-reference.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.