# Tool Reference (/mcp/tool-reference) Tools mirror the SparrowDesk Developer API. Knowledge Base collections and related endpoints require `VIEW_COLLECTIONS` and `MANAGE_COLLECTIONS`, which are included in the MCP default OAuth scope list. Other Knowledge Base behavior may still depend on additional scopes or account features. ## `get_me` Retrieve current SparrowDesk account information, not a user profile. No parameters. *** ## `get_conversation` Fetch a single conversation by its numeric ID. | Parameter | Type | Required | Description | | --------- | ------- | -------- | ------------------- | | `id` | integer | Yes | The conversation ID | *** ## `list_conversations` List conversations with optional filters, sorting, and pagination. | Parameter | Type | Required | Description | | ----------------------- | ----------------- | -------- | ------------------------------------------------------------------------------------------- | | `starting_after` | string | No | Pagination cursor | | `per_page` | integer | No | Items per page, 1–100 (default: 25) | | `status` | array | No | Filter by status: `Open`, `Pending`, `Resolved`, `Closed` | | `priority` | array | No | Filter by priority: `Low`, `Medium`, `High`, `Urgent` | | `assigned_to_member_id` | array of integers | No | Filter by assigned agent IDs | | `assigned_to_team_id` | array of integers | No | Filter by assigned team IDs | | `brand_id` | array of integers | No | Filter by brand IDs | | `requested_by_id` | integer | No | Filter by requestor contact ID | | `requested_by_company` | integer | No | Filter by requester contact company ID. Intersects with `requested_by_id` when both are set | | `sort_by` | string | No | `created_at` or `updated_at` (default: `created_at`) | | `sort_order` | string | No | `asc` or `desc` (default: `desc`) | *** ## `list_conversations_with_replies` List conversations with their replies inlined in a single call. Uses the same filters as `list_conversations`, plus reply-level controls. The root `pages` and `total_count` apply to conversations only; each conversation row carries its own `replies` object shaped like the `list_conversation_replies` response. | Parameter | Type | Required | Description | | ----------------------- | ----------------- | -------- | -------------------------------------------------------------- | | `starting_after` | string | No | Cursor for conversation list pagination | | `per_page` | integer | No | Conversations per page, 1–20 (default: 20) | | `replies_per_page` | integer | No | Replies per conversation, 1–50 (default: 50) | | `replies_sort_order` | string | No | Reply sort by `sent_at`: `asc` or `desc` (default: `desc`) | | `type` | string | No | Filter replies by `INTERNAL_NOTE` or `REPLY` | | `status` | array | No | Filter by status: `Open`, `Pending`, `Resolved`, `Closed` | | `priority` | array | No | Filter by priority: `Low`, `Medium`, `High`, `Urgent` | | `assigned_to_member_id` | array of integers | No | Filter by assigned agent IDs | | `assigned_to_team_id` | array of integers | No | Filter by assigned team IDs | | `brand_id` | array of integers | No | Filter by brand IDs | | `requested_by_id` | integer | No | Filter by requestor contact ID | | `handled_by_ai_agent` | boolean | No | Filter by whether the conversation was handled by the AI agent | | `sort_by` | string | No | `created_at` or `updated_at` (default: `created_at`) | | `sort_order` | string | No | `asc` or `desc` (default: `desc`) | *** ## `create_conversation` Create a new conversation/ticket in SparrowDesk. | Parameter | Type | Required | Description | | --------------- | ------- | -------- | ------------------------------------------------------------ | | `subject` | string | Yes | Conversation subject | | `description` | string | Yes | Conversation description | | `requested_by` | string | Yes | Email or phone number of the requester | | `priority` | string | No | `Low`, `Medium`, `High`, or `Urgent` (default: `Medium`) | | `source` | string | No | `Mail` or `Call` (default: `Call`) | | `status` | string | No | `Open`, `Pending`, `Resolved`, or `Closed` (default: `Open`) | | `brand_id` | integer | No | Brand ID (uses account default if omitted) | | `assignee` | string | No | Agent email address to assign the conversation to | | `team_id` | integer | No | Team ID to assign the conversation to | | `custom_fields` | array | No | Array of `{ internal_name, value }` objects | *** ## `update_conversation` Patch an existing conversation. | Parameter | Type | Required | Description | | --------------- | ------- | -------- | --------------------------------------------------------------------- | | `id` | integer | Yes | Conversation ID | | `subject` | string | No | Conversation subject | | `priority` | string | No | `Low`, `Medium`, `High`, or `Urgent` | | `status` | string | No | `Open`, `Pending`, `Resolved`, or `Closed` | | `assignee` | string | No | Agent email address to assign the conversation to | | `team` | string | No | Team name | | `custom_fields` | array | No | Array of `{ internal_name, value }` objects. Values should be strings | *** ## `delete_conversation` Delete a conversation by ID. | Parameter | Type | Required | Description | | --------- | ------- | -------- | --------------- | | `id` | integer | Yes | Conversation ID | *** ## `list_conversation_replies` List replies for a conversation, with optional filtering and pagination. | Parameter | Type | Required | Description | | ---------------- | ------- | -------- | ------------------------------------ | | `id` | integer | Yes | The conversation ID | | `starting_after` | string | No | Pagination cursor | | `per_page` | integer | No | Items per page, 1–100 (default: 25) | | `type` | string | No | Filter by `INTERNAL_NOTE` or `REPLY` | | `sort_order` | string | No | `asc` or `desc` (default: `desc`) | *** ## `add_conversation_reply` Add a reply or internal note to a conversation. | Parameter | Type | Required | Description | | ------------ | ------- | -------- | -------------------------------------------------------------- | | `id` | integer | Yes | The conversation ID | | `reply_text` | string | Yes | The content of the reply | | `type` | string | Yes | `REPLY` (visible to customer) or `INTERNAL_NOTE` (agents only) | *** ## `list_conversation_fields` List ticket custom field definitions. | Parameter | Type | Required | Description | | ---------------- | ------- | -------- | ------------------------------ | | `starting_after` | string | No | Pagination cursor | | `per_page` | integer | No | Items per page | | `is_active` | boolean | No | Filter by active status | | `is_default` | boolean | No | Filter by default field status | *** ## `get_conversation_field` Fetch a single conversation field by ID. | Parameter | Type | Required | Description | | --------- | ------- | -------- | --------------------- | | `id` | integer | Yes | Conversation field ID | *** ## `create_conversation_field` Create a custom conversation field. | Parameter | Type | Required | Description | | ----------------------- | ------- | -------- | ------------------------------------------------------------------------------- | | `name` | string | Yes | Field name | | `type` | string | Yes | `single_line_text`, `multi_line_text`, `dropdown`, `number`, `date`, or `email` | | `internal_name` | string | No | Internal field name | | `description` | string | No | Field description | | `is_mandatory_on_close` | boolean | No | Whether the field is required before closing a conversation | | `field_options` | array | No | Field options. Required for dropdown fields | *** ## `update_conversation_field` Update a conversation field. | Parameter | Type | Required | Description | | ----------------------- | ------- | -------- | ----------------------------------------------------------- | | `id` | integer | Yes | Conversation field ID | | `name` | string | No | Field name | | `description` | string | No | Field description | | `is_active` | boolean | No | Whether the field is active | | `is_mandatory_on_close` | boolean | No | Whether the field is required before closing a conversation | | `field_options` | array | No | Field options | *** ## `list_contacts` List contacts with filters. | Parameter | Type | Required | Description | | -------------------- | ------- | -------- | ----------------- | | `search` | string | No | Search contacts | | `requested_by_email` | string | No | Filter by email | | `requested_by_phone` | string | No | Filter by phone | | `starting_after` | string | No | Pagination cursor | | `per_page` | integer | No | Items per page | *** ## `create_contact` Create a new contact. Either `email` or `phone` must be provided. | Parameter | Type | Required | Description | | --------------- | ------- | -------- | ---------------------------------------------- | | `first_name` | string | Yes | Contact's first name | | `last_name` | string | No | Contact's last name | | `email` | string | No | Email address (required if phone not provided) | | `phone` | string | No | Phone number (required if email not provided) | | `company_id` | integer | No | ID of the company to associate with | | `custom_fields` | object | No | Custom field key-value pairs | *** ## `update_contact` Update an existing contact. | Parameter | Type | Required | Description | | --------------- | ------- | -------- | ----------------------------------- | | `id` | integer | Yes | The contact ID to update | | `first_name` | string | No | Contact's first name | | `last_name` | string | No | Contact's last name | | `email` | string | No | Email address | | `phone` | string | No | Phone number | | `company_id` | integer | No | ID of the company to associate with | | `blocked` | boolean | No | Whether the contact is blocked | | `custom_fields` | object | No | Custom field key-value pairs | *** ## `get_contact` Fetch a single contact by its numeric ID. | Parameter | Type | Required | Description | | --------- | ------- | -------- | -------------- | | `id` | integer | Yes | The contact ID | *** ## `delete_contact` Delete a contact by ID. | Parameter | Type | Required | Description | | --------- | ------- | -------- | ----------- | | `id` | integer | Yes | Contact ID | *** ## `bulk_create_contacts` Bulk create contacts. The response includes a `job_id` that can be polled with `get_bulk_job_status`. | Parameter | Type | Required | Description | | ---------- | ----- | -------- | -------------------------------------------------------------------------------------------------------------------------- | | `contacts` | array | Yes | Contacts to create. Each object may include `first_name`, `last_name`, `email`, `phone`, `company_id`, and `custom_fields` | *** ## `get_bulk_job_status` Poll a bulk contact job until it is completed or failed. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------- | | `job_id` | string | Yes | Bulk contact job ID | *** ## `list_companies` List companies. | Parameter | Type | Required | Description | | ---------------- | ------- | -------- | ------------------- | | `starting_after` | string | No | Pagination cursor | | `per_page` | integer | No | Items per page | | `domain` | string | No | Exact domain filter | | `name` | string | No | Exact name filter | *** ## `get_company` Fetch a single company by its numeric ID. | Parameter | Type | Required | Description | | --------- | ------- | -------- | -------------- | | `id` | integer | Yes | The company ID | *** ## `create_company` Create a new company. | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------------------------ | | `name` | string | Yes | Company name | | `domain` | string | No | Lowercase domain like `example.com` or `company.co.uk` | | `address` | string | No | Company address | | `notes` | string | No | Free-form notes about the company | *** ## `update_company` Update an existing company. At least one field must be provided. | Parameter | Type | Required | Description | | --------- | ------- | -------- | ------------------------------------------------------ | | `id` | integer | Yes | The company ID to update | | `name` | string | No | Company name | | `domain` | string | No | Lowercase domain like `example.com` or `company.co.uk` | | `phone` | string | No | Company phone number | | `address` | string | No | Company address | | `notes` | string | No | Free-form notes about the company | *** ## `list_contact_fields` Retrieve all contact fields defined in the account. | Parameter | Type | Required | Description | | --------- | ------- | -------- | ----------------------------- | | `search` | string | No | Search contact fields by name | | `page` | integer | No | Page number for pagination | | `limit` | integer | No | Results per page | *** ## `list_members` Retrieve a paginated list of all team members in the account. | Parameter | Type | Required | Description | | ---------------- | ------- | -------- | ----------------------------------- | | `starting_after` | string | No | Pagination cursor | | `per_page` | integer | No | Items per page, 1–100 (default: 25) | *** ## `list_tags` List tags. | Parameter | Type | Required | Description | | ---------------- | ------- | -------- | ----------------- | | `starting_after` | string | No | Pagination cursor | | `per_page` | integer | No | Items per page | | `search` | string | No | Search tags | *** ## Knowledge Base tools Use `list_helpcenters` first to obtain a `helpCenterId`. Collections and articles are scoped per help center and brand. ## `list_helpcenters` List help centers. No parameters. *** ## `list_collections` List Knowledge Base collections for a help center. | Parameter | Type | Required | Description | | -------------- | ------- | -------- | ----------------------- | | `helpCenterId` | integer | Yes | Help center ID | | `page` | integer | No | Page number | | `limit` | integer | No | Results per page | | `collectionId` | integer | No | Filter by collection ID | | `isRoot` | boolean | No | Filter root collections | *** ## `get_collection` Get a collection with subcollections and articles. | Parameter | Type | Required | Description | | --------- | ------- | -------- | ----------------------------- | | `id` | integer | Yes | Collection ID | | `page` | integer | No | Page number for articles | | `limit` | integer | No | Results per page for articles | *** ## `create_collection` Create a Knowledge Base collection. | Parameter | Type | Required | Description | | -------------------- | ------- | -------- | ---------------------- | | `name` | string | Yes | Collection name | | `helpCenterId` | integer | Yes | Help center ID | | `brandId` | integer | Yes | Brand ID | | `description` | string | No | Collection description | | `parentCollectionId` | integer | No | Parent collection ID | *** ## `list_articles` List articles for a help center. | Parameter | Type | Required | Description | | -------------- | ------- | -------- | ------------------------- | | `helpCenterId` | integer | Yes | Help center ID | | `published` | boolean | No | Filter published articles | | `draft` | boolean | No | Filter draft articles | | `archived` | boolean | No | Filter archived articles | | `page` | integer | No | Page number | | `limit` | integer | No | Results per page | | `search` | string | No | Search articles | | `collectionId` | integer | No | Filter by collection ID | *** ## `get_article` Get one article. | Parameter | Type | Required | Description | | --------- | ------- | -------- | ----------- | | `id` | integer | Yes | Article ID | *** ## `create_article` Create an article as a draft or publish it. | Parameter | Type | Required | Description | | -------------- | ------- | -------- | ---------------------------------------------------------------- | | `helpCenterId` | integer | Yes | Help center ID | | `brandId` | integer | Yes | Brand ID | | `title` | string | No | Article title | | `content` | string | No | Article content as HTML | | `publish` | boolean | No | Whether to publish the article | | `collectionId` | integer | No | Collection ID | | `isPublic` | boolean | No | Whether the article is public. Publish flow follows the API docs | *** ## `update_article` Update an article draft or publish it. | Parameter | Type | Required | Description | | ------------------ | --------------- | -------- | ----------------------------------------------------- | | `id` | integer | Yes | Article ID | | `title` | string | No | Article title | | `content` | string | No | Article content as HTML | | `collectionId` | integer or null | No | Collection ID. Use `null` to remove from a collection | | `brandId` | integer | No | Brand ID | | `publish` | boolean | No | Whether to publish the article | | `isPublic` | boolean | No | Whether the article is public | | `aiAgentEnabled` | boolean | No | Whether the article is enabled for AI Agent | | `aiCopilotEnabled` | boolean | No | Whether the article is enabled for AI Copilot | *** ## `archive_article` Archive an article. | Parameter | Type | Required | Description | | --------- | ------- | -------- | ----------- | | `id` | integer | Yes | Article ID |