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`)

`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

`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.

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

Tool Reference

On this page