MCP Tools Reference
Tools are actions that AI assistants can perform on your behalf. The Tailwind MCP Server provides tools for finding accounts, boards, and recommended posting times, for creating, scheduling, listing, or deleting Pinterest Pins, and for generating Pin drafts from a URL with Tailwind’s AI.
list_accounts
Section titled “list_accounts”List all Pinterest accounts connected to your Tailwind organization. Call this first because every other tool requires an accountId returned by this tool.
This tool has no parameters.
Example Usage
Section titled “Example Usage”“List my Pinterest accounts”
Response
Section titled “Response”Returns each account’s ID, username, display name, domain-verification status, and Pinterest-token status.
list_boards
Section titled “list_boards”List the Pinterest boards on an account, with each board’s numeric ID and name. Use this to find a boardId for create_post or schedule_post — board IDs are numeric, never board names or URLs.
Parameters
Section titled “Parameters”| Parameter | Type | Required | Description |
|---|---|---|---|
accountId |
string | Yes | Numeric Tailwind account ID returned by list_accounts |
Example Usage
Section titled “Example Usage”“Which boards do I have on account 123456?”
Response
Section titled “Response”Returns each board’s ID, name, and whether it is secret or a collaborator board.
list_timeslots
Section titled “list_timeslots”List the account’s smart schedule timeslots — Tailwind’s recommended posting times. Each slot is a recurring weekly time (day of week + time of day + timezone), not a concrete date: to schedule at a recommended time, the assistant computes the next future occurrence of a slot and passes it as sendAt.
Parameters
Section titled “Parameters”| Parameter | Type | Required | Description |
|---|---|---|---|
accountId |
string | Yes | Numeric Tailwind account ID returned by list_accounts |
Example Usage
Section titled “Example Usage”“When should I schedule my next pin on account 123456?”
Response
Section titled “Response”Returns each timeslot’s ID, day of week, time of day (24-hour HH:MM), timezone, and how it was added to the schedule.
create_post
Section titled “create_post”Create a new Pinterest Pin from an image or video URL. Without sendAt it is saved as a draft; with sendAt it is scheduled to publish, which also requires title, description, url, and boardId. There is no update or edit tool — to change a Pin, delete it with delete_post and create a new one; to schedule an existing draft, use schedule_post.
Parameters
Section titled “Parameters”| Parameter | Type | Required | Description |
|---|---|---|---|
accountId |
string | Yes | Numeric Tailwind account ID returned by list_accounts |
mediaUrl |
string | Yes | URL of the image or video to pin |
mediaType |
string | No | Type of media: image (default) or video |
title |
string | Conditional | Pin title (max 100 characters). Required when sendAt is provided. |
description |
string | Conditional | Pin description (max 500 characters). Required when sendAt is provided. |
url |
string | Conditional | Destination URL when the pin is clicked. Required when sendAt is provided. |
boardId |
string | Conditional | Target Pinterest board ID — the numeric board ID from list_boards, not a board name or URL. Required when sendAt is provided. |
altText |
string | No | Alt text for accessibility (max 500 characters) |
isSimplifiedPin |
boolean | No | Whether to create a simplified pin (default: true). Set to false for a standard pin. |
sendAt |
string | No | When to publish (ISO 8601 format). Must be in the future. Omit for draft. Requires title, description, url, and boardId. |
productTagPinIds |
array | No | Pinterest product-catalog pin IDs to tag on the pin (business accounts only; max 24). Providing any forces a simplified pin. |
Example Usage
Section titled “Example Usage”“Create a pin on account 123456 with this image https://example.com/photo.jpg, title it ‘Summer Recipes’, and schedule it for January 20th at 2pm UTC”
Response
Section titled “Response”The tool returns a confirmation with:
- Post ID
- Status (draft or queued)
- Scheduled time (if applicable)
- Board information
schedule_post
Section titled “schedule_post”Schedule or reschedule an existing draft or queued Pin to publish at a specific time, by postId (from create_post or list_posts). The Pin must already have title, description, and url set; a draft without a board also needs boardId. Does not work on published Pins. To create and schedule a new Pin in one step, use create_post with sendAt instead.
Parameters
Section titled “Parameters”| Parameter | Type | Required | Description |
|---|---|---|---|
accountId |
string | Yes | Numeric Tailwind account ID returned by list_accounts |
postId |
string | Yes | Post ID to schedule |
sendAt |
string | Yes | When to publish (ISO 8601 format). Must be in the future. |
boardId |
string | Conditional | Target Pinterest board ID — the numeric board ID from list_boards, not a board name or URL. Required when scheduling a draft that doesn’t already have a board. |
Example Usage
Section titled “Example Usage”“Schedule post post_abc123 on account 123456 for tomorrow at 9am”
Response
Section titled “Response”Returns the updated post with:
- Post ID
- New status (queued)
- Scheduled time
delete_post
Section titled “delete_post”Permanently delete a Pin that has not been published to Pinterest. Published Pins cannot be deleted through Tailwind. Since there is no update tool, changing a Pin means deleting it and recreating it with create_post.
Parameters
Section titled “Parameters”| Parameter | Type | Required | Description |
|---|---|---|---|
accountId |
string | Yes | Numeric Tailwind account ID returned by list_accounts |
postId |
string | Yes | Post ID to delete |
Example Usage
Section titled “Example Usage”“Delete post post_abc123 from account 123456”
Response
Section titled “Response”Confirms the post was deleted with the post ID.
list_posts
Section titled “list_posts”List an account’s Pins — drafts, scheduled (queued), or published (sent) — with optional filtering by status. Returns each Pin’s postId for use with schedule_post and delete_post.
Parameters
Section titled “Parameters”| Parameter | Type | Required | Description |
|---|---|---|---|
accountId |
string | Yes | Numeric Tailwind account ID returned by list_accounts |
status |
string | No | Filter by status: draft, queued, sent, or uploading. Default: queued |
limit |
number | No | Number of posts to return (1-100). Default: 50 |
cursor |
string | No | Pagination cursor from previous response |
startDate |
string | No | Filter posts after this date (ISO 8601). Required for sent/uploading status. |
endDate |
string | No | Filter posts before this date (ISO 8601). Required for sent/uploading status. |
Example Usage
Section titled “Example Usage”“Show me all draft posts on account 123456”
“List the last 10 sent posts from January 2024”
Response
Section titled “Response”Returns a list of posts with:
- Post ID
- Status
- Scheduled/sent time
- Title (if set)
- Pagination cursor for next page
generate_pins_from_url
Section titled “generate_pins_from_url”Have Tailwind’s AI generate Pinterest Pin drafts from a web page — a blog post, product page, or article URL. Asynchronous and metered: each generation spends plan credits by design tier (approximately 3 for basic, 7 for premium, 1 for no-template — resolved server-side) and typically completes in 1–3 minutes. Returns a generation ID to poll with get_generation_status; the finished drafts appear in list_posts (status draft) carrying a matching generationId.
Calling this again for the same URL while a generation is in flight returns the same generation with deduplicated: true and charges nothing. Repeating the call after it completes starts — and charges — a new generation, so poll before retrying. If the URL already has a SmartPin on this account, that record is reused as-is (its stored design configuration applies and tier parameters are ignored); a SmartPin for the URL on a different account is a conflict.
Parameters
Section titled “Parameters”| Parameter | Type | Required | Description |
|---|---|---|---|
accountId |
string | Yes | Numeric Tailwind account ID returned by list_accounts |
url |
string | Yes | The web page to generate Pins from (http/https, max 2048 characters). Query parameters and fragments are ignored — variants of one page count as the same URL. |
title |
string | No | Display name for this generation source in the Tailwind dashboard (max 256 characters). Defaults to the URL. |
designTier |
string | No | basic (default), premium, or no-template. Determines the credit cost. |
premiumStyle |
string | Conditional | Visual style for premium designs: image-highlight, text-highlight, minimalist, artistic, professional, or natural. Required when designTier is premium; must be omitted otherwise. |
keywords |
array | No | Up to 10 keywords to guide the generated Pin copy |
Example Usage
Section titled “Example Usage”“Generate some Pins from my latest blog post https://example.com/blog/summer-recipes on account 123456”
Response
Section titled “Response”Returns the generation with:
- Generation ID (poll it with
get_generation_status) - Status (
processing) - Design tier and nominal credit cost
- Whether an existing SmartPin was reused, and whether the call deduplicated onto an in-flight generation
get_generation_status
Section titled “get_generation_status”Poll a Pin generation started by generate_pins_from_url. Generation typically completes in 1–3 minutes: poll every ~15 seconds and don’t give up before ~30 minutes — a hung generation can stay processing for ~25 minutes before the terminal generation-request-timed-out status appears. A “not found” response within ~10 seconds of starting the generation is a transient indexing artifact — retry it.
Parameters
Section titled “Parameters”| Parameter | Type | Required | Description |
|---|---|---|---|
generationId |
string | Yes | Generation ID returned by generate_pins_from_url |
Example Usage
Section titled “Example Usage”“Is my Pin generation done yet?”
Response
Section titled “Response”Returns the generation’s status (processing, success, or failed), the source URL, timestamps, and — on failure — a stable failureCode (for example scrape-failed, no-images-on-page, not-enough-credits, or generation-request-timed-out). On success, list the account’s draft posts and filter by the matching generationId to find the generated Pins.
Tool Availability
Section titled “Tool Availability”All tools require an authenticated Tailwind connection, using OAuth or an API key. Tools are automatically available to the AI assistant once the server is connected.
Error Handling
Section titled “Error Handling”When a tool encounters an error, the AI assistant will explain what went wrong. Common errors include:
| Error | Description | Solution |
|---|---|---|
| Account not found | The account ID doesn’t exist | Verify the account ID with list_accounts |
| Post not found | The post ID doesn’t exist | Check the post ID is correct |
| Cannot delete sent post | Post has already been published | Only posts not yet published can be deleted |
| Invalid sendAt | Schedule time is in the past | Use a future date/time |
Best Practices
Section titled “Best Practices”- Always verify account IDs first - Use
list_accountsto get valid IDs - Provide complete information - Include title, description, and URL for best results
- Use clear scheduling language - Say “January 20th at 2pm EST” rather than “next week”
- Review before publishing - Create drafts first if you want to review before scheduling