MCP tools reference

The SnowDots MCP server exposes 24 tools. Every tool acts as the connected member, inside the connection’s one agency, and only sees the clients and artifacts that member can reach. Tools return plain text meant for the model to read; errors explain what to call next.

Permission is the scope the connection needs. Tools a connection has no permission for are hidden from its tool list. Role notes an extra requirement on the member’s role or client access level.

Tool	Permission	Purpose
`whoami`	any	Which account, agency and permissions this is
`get_context`	`artifacts:read`	Agency guidelines and client brief
`list_inbox`	`artifacts:read`	What needs the member
`mark_inbox_done`	`artifacts:write`	Clear an inbox item
`list_artifacts`	`artifacts:read`	List artifacts
`create_artifact`	`artifacts:write`	Start a draft
`create_upload`	`artifacts:write`	Reserve an upload
`finalize_upload`	`artifacts:write`	Commit an upload as a version
`submit_content`	`artifacts:write`	Commit small HTML/Markdown in one call
`submit_for_review`	`artifacts:submit`	Ask a publisher to review
`get_publish_status`	`artifacts:read`	Where an artifact is
`list_comments`	`artifacts:read`	Read feedback
`add_comment`	`artifacts:write`	Comment or reply
`resolve_comment`	`artifacts:write`	Resolve a thread
`set_artifact_tags`	`artifacts:write`	Label an artifact for the team
`set_artifact_client`	`artifacts:write`	File under a client
`list_spaces`	`artifacts:read`	A client’s spaces
`file_artifact`	`artifacts:write`	File under spaces
`list_clients`	`artifacts:read`	Active clients
`list_contacts`	`artifacts:read`	A client’s contacts
`create_client`	`clients:write`	Add a client
`update_client`	`clients:write`	Edit a client or its brief
`create_contact`	`clients:write`	Add a contact
`update_contact`	`clients:write`	Edit a contact

Wherever a tool takes client, pass the client’s slug or id from list_clients.

Account and context

`whoami`

Identify the SnowDots account, agency and permissions this connection belongs to.

Permission: any connection
Parameters: none
Returns: your email and role, the agency name, slug and id, the connection’s scopes, and how many artifacts the agency holds.

Connected to SnowDots as sam@example.com, publisher of the agency "Northwind" (northwind, id …).
This connection may: artifacts:read, artifacts:write, artifacts:submit.

`get_context`

Read the team’s shared context before drafting: the agency guidelines and, for a client, its brief, contacts, recent artifacts and open feedback. It’s team-only — follow it, never quote it to clients.

Permission: artifacts:read

Parameter	Type	Required	Description
`client`	string	no	Client slug or id. Leave out for the agency guidelines and client list.

`list_inbox`

What needs the connected member: artifacts waiting for their review, client threads waiting for a reply, and their open inbox items (mentions, change requests, client comments). A good first call in any session.

Permission: artifacts:read
Parameters: none
Returns: three sections with counts; inbox items include the item_id for mark_inbox_done.

`mark_inbox_done`

Mark one of the member’s inbox items as done.

Permission: artifacts:write

Parameter	Type	Required	Description
`item_id`	string	yes	The item id from `list_inbox`.

Artifacts and versions

`list_artifacts`

List the artifacts in the agency, most recently updated first.

Permission: artifacts:read
Parameters: none
Returns: one line per artifact — id, title, type, format, status, version count, client and tags.

#42 — "September performance report" (Report, HTML, Draft, 2 version(s)) for Brightline Dental [tags: monthly]

`create_artifact`

Create a draft artifact. The format is fixed: every later version must match it.

Permission: artifacts:write

Parameter	Type	Required	Description
`title`	string	yes	Shown to the client, e.g. “September performance report”. Max 255 characters.
`format`	`html` \| `pdf` \| `markdown`	yes	The artifact’s format.
`client`	string	no	An active client, by slug or id.
`type`	`report` \| `dashboard` \| `presentation` \| `website_mockup` \| `insight`	no	What the artifact is.
`reporting_period`	string	no	Period covered, shown to the client, e.g. “Q3 2026”. Max 100 characters.

Returns the new artifact id.

`create_upload`

Reserve an upload slot for a new version of an existing artifact. Then PUT the bytes to the returned URL and call finalize_upload. See Upload workflow.

Permission: artifacts:write
Role: Contribute or higher on the artifact’s client

Parameter	Type	Required	Description
`artifact_id`	integer	yes	The artifact to add a version to.
`original_filename`	string	yes	File name with extension, e.g. `september.pdf`.
`mime_type`	string	yes	Content type, e.g. `application/pdf`. Must match the extension and the artifact format.
`byte_size`	integer	yes	Exact size in bytes, at most 25 MB.
`checksum`	string	no	SHA-256 hex digest, verified on finalize.

Returns the upload id, the signed upload URL, content type and expiry (15 minutes).

`finalize_upload`

Commit a reserved upload as a new immutable version. Only call it after the bytes were PUT.

Permission: artifacts:write
Role: Contribute or higher on the artifact’s client

Parameter	Type	Required	Description
`artifact_id`	integer	yes	The artifact the upload belongs to.
`upload_id`	string	yes	The upload id from `create_upload`.

Returns the version number, byte size and SHA-256. Fails if the file is missing, expired, already finalized, the wrong size, not a valid document of the artifact’s format, or doesn’t match the checksum.

`submit_content`

Commit a small HTML or Markdown body as a new immutable version in one call, with no upload step.

Permission: artifacts:write
Role: Contribute or higher on the artifact’s client

Parameter	Type	Required	Description
`artifact_id`	integer	yes	The artifact to add a version to.
`filename`	string	yes	With the right extension, e.g. `report.html` or `report.md`.
`content`	string	yes	The full document text, at most 256 KB.

Not for PDF artifacts — use create_upload.

Review

`submit_for_review`

Ask a publisher to review a finalized version of a draft artifact. It doesn’t publish: a person approves it in SnowDots.

Permission: artifacts:submit
Role: Contribute or higher on the artifact’s client

Parameter	Type	Required	Description
`artifact_id`	integer	yes	The draft artifact.
`version`	integer	no	Version number to submit. Defaults to the latest.

`get_publish_status`

Show where an artifact is — draft, in review, published or archived — its latest version, the live version, the version waiting for review, and any note from the reviewer.

Permission: artifacts:read

Parameter	Type	Required	Description
`artifact_id`	integer	yes	The artifact to check.

"September performance report" (#42) is in review.
Latest version: v3.
Live version: v2.
Waiting for review: v3.

Comments

`list_comments`

Read the comment threads on an artifact — client feedback and team notes — with the version each was left on, where it points, and replies.

Permission: artifacts:read

Parameter	Type	Required	Description
`artifact_id`	integer	yes	The artifact.
`include_resolved`	boolean	no	Also show resolved threads. Default `false`.

Each thread shows its author and audience — (client), (team) or (internal) — and [CHANGE REQUEST] when it asks for a change. Anchored comments show the CSS selector or PDF page and position, and the quoted text.

`add_comment`

Comment on an artifact or reply to a thread. Non-internal comments are visible to the client’s contacts on their share link.

Permission: artifacts:write

Parameter	Type	Required	Description
`artifact_id`	integer	yes	The artifact.
`body`	string	yes	Comment text, max 5,000 characters.
`internal`	boolean	no	`true` for a team-only note the client never sees.
`reply_to`	integer	no	Comment id to reply to.
`change_request`	boolean	no	`true` when it asks for a change; it stays open until resolved.
`mentions`	string[]	no	Emails of teammates to @mention (max 20). Write “@Their Name” in the body where it belongs, or the mention goes first.
`anchor`	object	no	The spot it’s about — see below.

Anchors use the same shape list_comments shows:

// HTML / Markdown
{ "kind": "text", "selector": "main > section:nth-of-type(2) > p", "quote": { "exact": "Bookings rose 18%" }, "viewport": { "w": 1280 } }

// PDF — x and y are 0..1 of the page
{ "kind": "point", "page": 3, "point": { "x": 0.42, "y": 0.6 } }

kind is text, element or point for HTML/Markdown, and point or text for PDFs.

`resolve_comment`

Mark a thread as dealt with, for example after a new version addresses it.

Permission: artifacts:write

Parameter	Type	Required	Description
`artifact_id`	integer	yes	The artifact.
`comment_id`	integer	yes	The thread to resolve.
`addressed_in_version`	integer	no	The version number that made the change.

Organising

`set_artifact_tags`

Replace an artifact’s tags. Existing tags are reused by name; new names create tags. Tags are team-only and never shown to clients.

Permission: artifacts:write
Role: Contribute or higher on the artifact’s client

Parameter	Type	Required	Description
`artifact_id`	integer	yes	The artifact.
`tags`	string[]	yes	Up to 20 names, each up to 40 characters. Empty list clears them.

`set_artifact_client`

File an artifact under a client, or pass an empty client to unfile it. Existing share links aren’t moved.

Permission: artifacts:write
Role: owner, admin or publisher, with Approve on the artifact’s client

Parameter	Type	Required	Description
`artifact_id`	integer	yes	The artifact.
`client`	string	no	An active client by slug or id; empty to unfile.

`list_spaces`

List a client’s active spaces with their ids and artifact counts.

Permission: artifacts:read

Parameter	Type	Required	Description
`client`	string	yes	Client slug or id.

`file_artifact`

File an artifact under spaces of its client, replacing the spaces it was under. An empty list keeps it on the client itself. Spaces decide which contacts can open it.

Permission: artifacts:write
Role: owner, admin or publisher, with Approve on the artifact’s client

Parameter	Type	Required	Description
`artifact_id`	integer	yes	The artifact.
`spaces`	string[]	yes	Space ids from `list_spaces` (max 50); empty to unfile.

Clients and contacts

`list_clients`

List the agency’s active clients with their slug and id.

Permission: artifacts:read
Parameters: none

`list_contacts`

List the active contacts at one client — the people who receive its reports.

Permission: artifacts:read

Parameter	Type	Required	Description
`client`	string	yes	Client slug or id.

`create_client`

Add a client to the agency. Returns its slug.

Permission: clients:write
Role: owner, admin or publisher

Parameter	Type	Required	Description
`name`	string	yes	e.g. “Brightline Dental”.
`contact_email`	string	no	The client’s main email address.
`notes`	string	no	Team-only brief (goals, KPIs, tone). Max 20,000 characters.

`update_client`

Change a client’s name, contact email or brief, or append a learning to the brief. Fields you leave out keep their value; the slug never changes.

Permission: clients:write
Role: owner, admin or publisher

Parameter	Type	Required	Description
`client`	string	yes	Client slug or id.
`name`	string	no	New name.
`contact_email`	string \| null	no	New main email; `null` clears it.
`notes`	string \| null	no	Replaces the whole brief; `null` clears it.
`append_to_brief`	string	no	One learning (max 2,000 characters) added to the end of the brief, dated and attributed to you.

`create_contact`

Add a person at a client who will receive its reports. Adding a contact doesn’t share anything with them.

Permission: clients:write
Role: owner, admin or publisher

Parameter	Type	Required	Description
`client`	string	yes	Client slug or id.
`name`	string	yes	The person’s name.
`email`	string	yes	Must be unique within the client.
`role`	string	no	Job title, e.g. “Marketing lead”.

`update_contact`

Change a contact’s name, email or role. Fields you leave out keep their value.

Permission: clients:write
Role: owner, admin or publisher

Parameter	Type	Required	Description
`client`	string	yes	Client slug or id.
`contact`	string	yes	Contact id from `list_contacts`, or their current email.
`name`	string	no	New name.
`email`	string	no	New email.
`role`	string \| null	no	New job title; `null` clears it.