---
title: "Supported tools"
description: "Review Mindtickle MCP tool parameters, response fields, scopes, limits, and side effects."
contentType: "reference"
url: "https://developer.mindtickle.com/docs/mcp/tools/"
---
Use this reference to look up each tool's required scope, parameters, returned fields, and behavior. Each tool is listed under its group with its identifier and required scope.
The server returns only tools permitted by the access token's scopes through `tools/list`, and checks access on every `tools/call`. For authentication, token handling, and error codes, see [Build a custom client](/docs/mcp/build-a-custom-client/).
## Server endpoint
The Mindtickle MCP server is hosted on each Mindtickle instance. Use the following URL pattern:
```text
https://{mindtickle-instance-url}/mcp
```
Replace `{mindtickle-instance-url}` with the hostname of your Mindtickle instance (for example, `example.mindtickle.com`). Use only the hostname; do not include the protocol or any other path. The `/mcp` path is fixed and must not be modified.
**Transport:** The server supports MCP over HTTP. The protocol uses GET requests for streaming and POST requests for JSON-RPC communication. Authentication is required on every request; see [Build a custom client](/docs/mcp/build-a-custom-client/) for the authentication model, scopes, and token endpoint.
## Read-only tools
The list tools (`find_deals`, `find_companies`, `find_contacts`, and `find_rooms`) return up to 10 results per page by default. Use each tool's documented `limit` and `offset` parameters to retrieve more results. `mindtickle_search` has separate result and pagination behavior described below.
Search content mindtickle_search read:search
### mindtickle_search
Searches across Mindtickle learning content (including assets, modules, files, series, asset hubs, tags, and peers) using hybrid keyword and AI-powered semantic search. Results respect the user's existing content access permissions. The content library includes training modules, sales assets, battle cards, and playbooks.
#### Parameters
| Parameter | Type | Required | Description |
| -------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| `query` | string | Required | 1 to 512 characters. Can't contain `--`, `/*`, `*/`, or `;` (blocked to prevent SQL-injection-style patterns). |
| `limit` | integer | Optional | Minimum 1; maximum 100; default 15. Results per call. |
| `fetchPeers` | boolean | Optional | Default `true`. Include matching peer (colleague) profiles. |
| `fetchSeries` | boolean | Optional | Default `true`. Include matching training series. |
| `fetchModules` | boolean | Optional | Default `true`. Include matching training modules. |
| `fetchFiles` | boolean | Optional | Default `false`. Include matching files. |
| `fetchAssets` | boolean | Optional | Default `false`. Include matching assets. Set this to `true` to get the asset `id` needed for `create_room` or `edit_room`. |
| `fetchHubs` | boolean | Optional | Default `false`. Include matching asset hubs. |
:::note
Each `fetch*` flag controls whether full metadata is included for a matching content type. These flags do not filter which results are returned. Setting every flag to `false` still returns matches, with less metadata.
:::
#### Response
| Field | Type | Description |
| ----------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `items` | array | Up to `limit` items; an empty array on no matches. Each item includes a relevance `score`, matched excerpts in `matchingText`, and a `metaDetails` object whose fields depend on the result's content type and which `fetch*` flags were set. |
| `totalCount` | integer | Total number of matches, not just the ones included in this response. |
| `returnedCount` | integer | Number of items actually included in this response. |
| `hasNextPage` | boolean | Whether more results exist beyond this response. |
| `endCursor` | string | A pagination cursor. See the note below. |
| `entityWiseCount` | array | Optional. Match count broken down by entity type. |
:::note
`hasNextPage` and `endCursor` are always present, but this tool has no parameter for requesting a later page. Every call returns the first `limit` results by relevance. Narrow the `query` or increase `limit` within its allowed range to retrieve more relevant results.
:::
#### Example prompts
- "Find the latest battle card for competitor ABC."
- "Search my Mindtickle content for the onboarding module."
Ask Seller Copilot mindtickle_seller_copilot_ask read:copilot_chat
### mindtickle_seller_copilot_ask
Sends a conversation to Mindtickle's Seller Copilot and returns the assistant's response. Draws context from the calling user's own assigned training, sales assets, and Call AI recordings. Requires the client to maintain and send the full conversation history with each request. Supports optional streaming responses; see [Streaming responses](/docs/mcp/build-a-custom-client/#streaming-responses).
#### Parameters
| Parameter | Type | Required | Description |
| --------- | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `input` | string or array | Required | Either a single question as a string, or the full conversation so far as an array of `{role, content}` turns (`role` is `user` or `assistant`; `content` can't be empty). If you pass an array, its last turn's `role` must be `user`. |
Each call starts a new session. To continue a conversation, resend the full prior exchange in `input` with your new question as the final `user` turn. A previous response's `sessionId` cannot resume the session.
#### Response
| Field | Type | Description |
| ----------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `queryId` | string | Server-assigned ID for this query. |
| `sessionId` | string | Session identifier assigned to this exchange for logging and correlation. It cannot be passed back as a request parameter. |
| `fullText` | string | The assembled answer text. |
| `status` | string | `COMPLETED`, `IN_PROGRESS`, or `FAILED`. |
| `error` | object | Present when the service reports an error in a returned tool response. Includes `code` and `message`. |
:::note
If the underlying response stream stalls after some content has already arrived, the call resolves with whatever partial answer was generated rather than failing outright. Check `status` and `error` before treating `fullText` as complete.
:::
#### Example prompts
- "How do I improve my close rate on enterprise deals?"
- "Summarize my last call with Acme Corp."
Find deals find_deals read:rooms
### find_deals
Looks up deals (CRM opportunities) by name, company, or stage. Useful for finding the deal behind a Digital Sales Room, or for confirming whether a room already exists for one. Results are scoped to the calling user's organization. Every parameter is optional. An unfiltered call matches every deal in the organization, so filter whenever possible.
#### Parameters
| Parameter | Type | Required | Description |
| --------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `query` | string | Optional | Partial match against the deal name. |
| `company_ids` | string[] | Optional | Restricts results to one or more companies. |
| `stage` | string[] | Optional | Restricts results to one or more deal stages. Exact match. |
| `with_room` | boolean | Optional | `true` returns only deals that already have a room; `false` returns only deals without one; omit to return all deals. |
| `limit` | integer | Optional | Minimum 1; maximum 1,000, enforced by the server; default 10. Results per page. |
| `offset` | integer | Optional | Minimum 0. Number of matches to skip for pagination. |
| `include_total_count` | boolean | Optional | Default `false`. Adds `total_count` to the response, but only on the first page (when `offset` is omitted). Counting every match across a large pipeline can be slow, so pass this only when a count is actually needed. |
#### Response
| Field | Type | Description |
| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `total_count` | integer | Present only when `include_total_count: true` was passed, and only on the first page. Absence never means zero. |
| `deals` | array | Up to `limit` items; an empty array on no matches (a normal success response, not an error). Each item includes `deal_id`, `name`, `stage`, `amount`, `currency`, `close_date`, `next_step`, `crm_deal_id`, `company_id`, `company.name`, `owner.full_name`, `room_id` (UUID, nullable), and `room_id_int` (nullable). |
:::note
The tool returns an empty array when nothing matches, or up to `limit` records when matches exist. Both are successful responses. The client must select the intended deal when multiple records match; the tool does not select one automatically.
:::
#### Example prompts
- "Pull up the Acme Corp deal."
- "Show me all deals in the Negotiation stage for Acme Corp."
- "Which of my deals don't have a room yet?"
Find companies find_companies read:rooms
### find_companies
Looks up companies (CRM accounts) by name, so you can attach one to a Digital Sales Room for company-level branding and analytics. Matching is partial and case-insensitive. Results are scoped to the calling user's organization.
#### Parameters
| Parameter | Type | Required | Description |
| --------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query` | string | Optional | Part or all of the company name. Matching is partial and case-insensitive: a plain substring match, not exact and not embedding-based. Omit or pass an empty string to match every company. |
| `limit` | integer | Optional | Minimum 1; default 10. The documented maximum is 1,000. The tool's schema does not enforce this maximum; keep requests within the documented limit. |
| `offset` | integer | Optional | Minimum 0; zero-based. Number of matches to skip for pagination. |
#### Response
| Field | Type | Description |
| ------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
| `total_count` | integer | Total matches. Present on the first page only. |
| `companies` | array | Up to `limit` items; an empty array on no matches. Each item includes `company_id`, `name`, and `crm_company_id`. |
:::note
The tool returns an empty array when nothing matches, or up to `limit` matching companies. It does not rank results or select a best match.
:::
#### Example prompts
- "Do we have an account for Acme Corp?"
- "Find any companies with 'acme' in the name."
Find contacts find_contacts read:rooms
### find_contacts
Looks up buyer and prospect contacts by name, email, or associated company, so you can add them to a Digital Sales Room's guest list or invite them with `share_room`. Contacts are synced from your CRM, so a very recent change may not appear immediately.
#### Parameters
| Parameter | Type | Required | Description |
| ------------ | --------------------- | -------- | -------------------------------------------------------------------- |
| `query` | string | Optional | Whole-word match. Text containing `@` is treated as an email prefix. |
| `email` | string (email format) | Optional | Exact, complete email address. |
| `company_id` | string | Optional | Restricts results to one company's contacts. |
| `limit` | integer | Optional | Minimum 1; maximum 1,000, enforced by the server; default 10. |
| `offset` | integer | Optional | Minimum 0. Number of matches to skip for pagination. |
#### Response
| Field | Type | Description |
| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `total_count` | integer | Total matches. Present on the first page only. |
| `contacts` | array | Up to `limit` items; an empty array on no matches. Each item includes `contact_id`, `first_name`, `last_name`, `email`, `title`, `consent` (boolean or null), `company_id`, `crm_contact_id`, and `company.company_name`. |
:::note
There is no combined `name` field: build a display name from `first_name` + `last_name`. The `consent` field is informational only; nothing downstream, including `share_room`, enforces it before emailing a contact.
:::
#### Example prompts
- "Who's my main contact at Acme Corp?"
- "Find sarah@example.com in our contacts."
Find rooms find_rooms read:rooms
### find_rooms
Finds existing Digital Sales Rooms by name, or by the deal, company, or contact linked to them, and returns each room's identifiers for use with `fetch_room`, `edit_room`, and `share_room`. By default, returns only active rooms, most recently active first. Results include any room the calling user is permitted to see, which for a manager or admin can include rooms created by others.
#### Parameters
| Parameter | Type | Required | Description |
| ----------- | ------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------ |
| `query` | string | Optional | Free text matched against the room name, and the linked deal, company, or contact name or email. |
| `room_type` | array of enum: `deal`, `general`, `content_link`, `company` | Optional | Defaults to all four types. |
| `status` | array of enum: `ACTIVE`, `INACTIVE`, `DRAFT` | Optional | Defaults to `[ACTIVE]`. Case-sensitive. |
| `sort_by` | enum: `lastActivityAt`, `updatedAt`, `name`, `ownerName`, `visitorsCount` | Optional | Defaults to `lastActivityAt`, always sorted descending. |
| `limit` | integer | Optional | Minimum 1; maximum 1,000, enforced by the server; default 10. |
| `offset` | integer | Optional | Minimum 0. Number of matches to skip for pagination. |
#### Response
| Field | Type | Description |
| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `total_count` | integer | Total matches. Present on the first page only. |
| `rooms` | array | Up to `limit` items; an empty array on no matches. Each item includes `room_id` (UUID), `room_id_int` (numeric, as a string), `name`, `status`, `room_type`, `owner_name`, `visitors_count`, `visits_count`, `last_activity_at`, `link`, and nullable `deal` (`deal_id`, `deal_name`) and `company` (`company_id`, `company_name`) objects. |
:::note
This tool can't filter directly by `company_id`, `deal_id`, or `contact_id`. To find a room through a deal, use a non-null `room_id` returned by `find_deals`, then call `fetch_room`. You can first resolve a company with `find_companies` and pass its `company_id` in the `company_ids` array for `find_deals`. Do not pass a company ID or deal ID to `fetch_room`. Results include any room the calling user is permitted to see. For a manager or admin, this can include rooms created by others. If a deal or company has more than one room, each one appears as a separate entry; there's no deduplication or "most recent" selection.
:::
#### Example prompts
- "Is there already a room set up for the Acme Corp deal?"
- "Show me the rooms I've shared in the last month."
Get room details fetch_room read:rooms
### fetch_room
Retrieves the full details of a single Digital Sales Room by its ID, including its configuration and links and, when requested, its content and guest lists. Use this to confirm a room's current state or verify that a `create_room` or `edit_room` change took effect.
#### Parameters
| Parameter | Type | Required | Description |
| ----------------- | ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `room_id` | string (UUID) | Required | Must match a 36-character UUID pattern. The numeric `room_id_int` is rejected. Use the UUID returned by `find_rooms`, `find_deals`, or `create_room`. |
| `include_content` | boolean | Optional | Default `false`. Adds a `contents` array to the response. |
| `include_guests` | boolean | Optional | Default `false`. Adds a `guests` array to the response. |
#### Response
| Field | Type | Description |
| ---------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `room` | object or null | When non-null, includes `room_id`, `room_id_int`, `name`, `status`, `room_type`, `audience`, `layout`, `description`, `language`, `invited_contacts_only`, `requires_email`, `requires_passcode` (boolean only, the passcode itself is never returned), `requires_expiration_date`, `expires_at` (nullable), `domain_restricted`, `domains` (only for a caller who can edit the room; null otherwise), `enable_qa`, `enable_contact_card`, `enable_share`, `buyer_copilot_enabled`, `owner`, nullable `deal` and `company`, nullable `primary_guest`, `visitors_count`, `visits_count`, `room_contacts_count`, `conversation_threads_count`, `total_items`, `link`, `internal_link`, `expired`, `last_activity_at`, `created_at`, `updated_at`. |
| `contents` | array | Present only if `include_content: true` was passed. Each item includes `content_id`, `name`, `content_type`, `uuid`, and `description`. |
| `guests` | array | Present only if `include_guests: true` was passed. Each item includes `contact_id`, `first_name`, `last_name`, and `email`. |
:::note
A null `room` is a successful response. It can mean either that the room does not exist or that the caller lacks access; the response does not distinguish these cases. Do not treat it as proof that the room does not exist. Use `find_rooms` to look up an accessible room instead of retrying the same ID. Activity data is limited to the aggregate counters above; no per-guest or per-content breakdown is returned.
:::
#### Example prompts
- "What's in the room I shared with Acme Corp last month?"
- "Who has access to this room right now?"
## Write tools
These tools create or change data. `share_room` sends invitation emails and can also create contact records. `create_room`, `edit_room`, and `create_contacts` do not send emails. Review the tool's requirements and response fields before acting on its result.
Create a room create_room write:rooms
### create_room
Creates a new Digital Sales Room and returns its identifiers and links. The room goes live immediately, but no one is emailed until `share_room` is called. This tool creates a room without a template. If you need a templated room, create one from a room template in the Mindtickle web app instead.
#### Parameters
| Parameter | Type | Required | Description |
| -------------------------- | -------------------------------------------------- | ---------------------- | ----------------------------------------------------------------- |
| `name` | string, 1 to 250 characters | Required | Room title. |
| `room_type` | enum: `deal`, `general`, `content_link`, `company` | Required | `general` creates a standalone room with no CRM linkage. |
| `asset_ids` | string[], min 1 item | Required | At least one asset is required. A room can't be created empty. |
| `deal_id` | string | Conditionally required | Required only when `room_type` is `deal`. |
| `passcode` | string, min 1 character | Conditionally required | Required only when `requires_passcode` is `true`. |
| `expires_at` | integer (epoch seconds), min 1 | Conditionally required | Required only when `requires_expiration_date` is `true`. |
| `company_id` | string | Optional | Not specified. |
| `contact_ids` | string[], min 1 item if provided | Optional | Adds guests at creation. No one is emailed as a result. |
| `description` | string | Optional | Not specified. |
| `invited_contacts_only` | boolean | Optional | Default `true`. |
| `requires_email` | boolean | Optional | Default `false`. |
| `requires_passcode` | boolean | Optional | Default `false`. |
| `requires_expiration_date` | boolean | Optional | Default `false`. |
| `domains` | string[] | Optional | Each entry must start with `@`. |
| `enable_qa` | boolean | Optional | Default `true`. |
| `enable_contact_card` | boolean | Optional | Default `true`. |
| `enable_share` | boolean | Optional | No documented default. |
| `buyer_copilot_enabled` | boolean | Optional | Default `true`; also controlled by an organization-level setting. |
#### Response
| Field | Type | Description |
| --------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `errors` | string[] | A non-empty array means the room was not created, even though the call returned. |
| `message` | string | Human-readable message accompanying `errors`. |
| `room` | object, present only on success | `room_id`, `room_id_int`, `name`, `status` (always `ACTIVE` on creation), `room_type`, `link`, `internal_link`, `created_at`, `total_items`. |
:::note
The room owner is determined by the caller's identity and cannot be set through a parameter. The tool does not accept a template or send notifications, including to contacts added during creation.
`contact_ids` accepts only existing contacts. To add a new email address as a guest during creation, first call `create_contacts` and use the returned contact ID. Alternatively, call `share_room` after creating the room to create the contact and send an invitation.
:::
#### Example prompts
- "Set up a new room for Acme Corp with the latest pricing deck and case study."
- "Create a general room I can use for the security questionnaire."
Update a room edit_room write:rooms
### edit_room
Updates an existing Digital Sales Room: its name, description, linked deal or company, guest list, access controls, feature settings, and content. Only the fields you pass are changed, and a field you do pass replaces its current value entirely. Content can be added, but not removed or reordered, through this tool. No one is emailed as a result of these changes; use `share_room` to notify guests.
#### Parameters
| Parameter | Type | Required | Description |
| -------------------------- | -------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------- |
| `room_id_int` | string matching `^[0-9]+$` | Required | The numeric room ID (not the UUID `room_id`). |
| `name` | string, 1 to 250 characters | Optional | Not specified. |
| `description` | string | Optional | Not specified. |
| `deal_id` | string | Optional | Not specified. |
| `company_id` | string | Optional | Not specified. |
| `contact_ids` | string[], min 1 item if provided | Optional | Replaces the entire guest list: omitted contacts are removed, not left alone. |
| `invited_contacts_only` | boolean | Optional | Not specified. |
| `requires_email` | boolean | Optional | Not specified. |
| `requires_passcode` | boolean | Optional | Not specified. |
| `passcode` | string | Conditionally required | Required when `requires_passcode` is `true`. |
| `requires_expiration_date` | boolean | Optional | Not specified. |
| `expires_at` | integer (epoch seconds) | Conditionally required | Required when `requires_expiration_date` is `true`. |
| `domains` | string[] | Optional | Replaces the entire allowed-domains list, the same way `contact_ids` does. |
| `enable_qa` | boolean | Optional | Not specified. |
| `enable_contact_card` | boolean | Optional | Not specified. |
| `enable_share` | boolean | Optional | Not specified. |
| `buyer_copilot_enabled` | boolean | Optional | Not specified. |
| `add_assets` | boolean | Optional | Not specified. |
| `assets_to_add` | array of objects (`id`, `name`) | Conditionally required | Required when `add_assets` is `true`. Content can only be added through this tool, never removed or reordered. |
#### Response
| Field | Type | Description |
| ---------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `updateRoom.errors` | string[] | Can contain errors even when the tool call completes. Check this array to determine whether the update succeeded. |
| `updateRoom.message` | string | Status message. |
| `updateRoom.room` | object | Includes these 7 room fields: `room_id`, `room_id_int`, `name`, `status`, `link`, `internal_link`, `total_items`. |
| `addAssetsToRooms.all_contents_already_exists` | boolean | Present only when `add_assets: true` was passed. `true` means the asset was already in the room. Nothing new was added. |
| `addAssetsToRooms.selected_resource_not_found` | boolean | Present only when `add_assets: true` was passed. `true` means nothing was added. |
:::note
A supplied field replaces its current value; it is not merged. For example, `contact_ids` replaces the entire guest list. To add an item to an existing list, first call `fetch_room` and then send the complete updated list. For guest-list changes, set `include_guests: true` to retrieve the current guests and preserve their contact IDs in the updated list.
A returned response does not prove the update succeeded. Check `updateRoom.errors`. For asset additions, also check `addAssetsToRooms.all_contents_already_exists` and `addAssetsToRooms.selected_resource_not_found`. This tool can add content but cannot remove or reorder it.
:::
#### Example prompts
- "Add the new pricing sheet to the room I shared with Acme Corp."
- "Add John's manager to the Acme Corp room as a guest."
Share a room share_room write:rooms
### share_room
Emails an existing Digital Sales Room's link to one or more buyers by email address, inviting them to open it. This is the only tool that sends email on a room's behalf. `create_room` and `edit_room` never notify anyone.
#### Parameters
| Parameter | Type | Required | Description |
| ------------- | ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `room_id_int` | string matching `^[0-9]+$` | Required | The numeric room ID (not the UUID `room_id`). |
| `invitees` | array of objects, min 1, max 50 | Required | Each entry needs only an `email` field (email format, min 3 characters). There is no `contact_ids` parameter. The schema is strict, so passing one is rejected outright. |
#### Response
| Field | Type | Description |
| ---------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| `link` | string | The buyer-facing room link, the same one included in the invitation email. |
| `contacts` | array | The people actually invited and emailed. Each entry includes `contact_id`, `email`, `first_name`, `last_name`. |
| `errors` | string[] | Can be present even when the rest of the payload is non-null. |
| `message` | string | Human-readable message accompanying `errors`. |
:::note
`invitees` accepts email addresses, up to 50 per call. There is no `contact_ids` parameter. Compare the requested addresses with the returned `contacts` array: an address missing from that array was not emailed.
The entire response can be null if `room_id_int` does not identify a room in the caller's organization. In that case, no invitations are sent. For an invitee without an existing contact, the server creates a contact record automatically, whether or not you called `create_contacts` or `find_contacts` first.
:::
#### Example prompts
- "Send the Acme Corp room to sarah@example.com and her manager."
- "Invite jane@example.com to the room I just created."
Create contacts create_contacts write:rooms
### create_contacts
Finds or creates contacts from 1 to 50 email addresses for use in a Digital Sales Room's guest list. Returns existing contacts without creating duplicates and creates records for new addresses. It does not send email or associate contacts with a company or deal. Use `find_contacts` to look up a person by name.
#### Parameters
| Parameter | Type | Required | Description |
| --------- | ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `emails` | string[], min 1, max 50 | Required | Email addresses to resolve into contacts, one per person. Addresses are trimmed, lowercased, and deduplicated by the server before resolution. |
#### Response
| Field | Type | Description |
| --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `errors` | string[] | Batch-level errors. The tool can return these alongside other result data. |
| `message` | string | Human-readable message accompanying `errors`. |
| `results` | array | One entry per submitted email: `email`, `created` (boolean: `true` if a new contact was inserted, `false` if an existing one was reused), `error` (nullable, per-address failure reason), and a nested `contact` object (`contact_id`, `first_name`, `last_name`, `email`, `company_id`) that is null when that item's `error` is set. |
:::note
Calling this tool again for an existing email returns the existing contact with `created: false`. New contacts have no name or company until those details are added separately. Unlike the read tools, failed calls are not retried automatically.
The tool uses the same contact-creation behavior as `share_room`, but does not send an invitation. Check the batch-level `errors` and each result's `error` before using the returned contacts.
:::
#### Example prompts
- "Add jane@example.com and john@example.com as contacts so I can invite them to a room."
- "Create a contact for procurement@example.com."
## Timeouts
Each tool call is subject to a timeout. If the underlying operation doesn't complete within that time, the call fails with a timeout error.
| Tool(s) | Timeout |
| --------------------------------------------------------------------------- | ---------------- |
| `find_deals`, `find_companies`, `find_contacts`, `find_rooms`, `fetch_room` | 8 seconds |
| `create_room`, `edit_room` | 15 seconds |
| `share_room`, `create_contacts` | 10 seconds |
| `mindtickle_seller_copilot_ask` | 90 seconds |
| `mindtickle_search` | About 30 seconds |
Existing tools retain their names and required scopes as new tools are added. Check the scopes granted to your connection when discovering available tools.
## Related
- [Mindtickle MCP](/docs/mcp/): What the server does and how to decide which connection path applies to you.
- [Build a custom client](/docs/mcp/build-a-custom-client/): Authentication, scopes, and task-oriented setup for developers and integrators.
- [Set up the connector](/docs/mcp/publish-the-connector/): UI-based setup for IT admins.
- [Connect your account](/docs/mcp/connect-your-account/): Connecting for reps.
- [Use cases](/docs/mcp/use-cases/): Example workflows using the tools in this article.