Tailwind

Use this when the user wants Pin titles and descriptions written the way THEIR Tailwind account already writes them. This is not generic copywriting: it runs Tailwind's Ghostwriter against the organization's saved brand context — tone, style, and audience captured from their own content — and files the result in their Ghostwriter history so it is available in the dashboard alongside everything else they have generated. Prefer it over writing Pin copy yourself whenever the user has a Tailwind account, because you cannot see that brand context. Asynchronous and metered: each call spends the user's plan credits, takes under a minute, and returns a generation id to poll with get_copy_generation_status. Org-scoped — no accountId needed. Pinterest Pin copy only; it does not write blog posts, emails, or product listings. Every call generates and charges again, so poll the id you have rather than re-calling.

generate_pin_copy

Use this when the user wants Tailwind's AI to create Pinterest Pin drafts from a web page (a blog post, product page, or article URL). Asynchronous and metered: each generation spends the user's plan credits by design tier (approximately 3 for basic, 7 for premium, 1 for no-template/photo-only — resolved server-side), takes 1-3 minutes, and returns a generation id to poll with get_generation_status. Takes an accountId from list_accounts. Once the status is success, the 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 — but repeating the call after it completes starts and charges a NEW generation, so poll before retrying. If the user did not say which Pinterest account to use and list_accounts returns more than one, ask the user which account to use before calling this — do not choose for them.

generate_pins_from_url

Use this when the user asks how a specific Pin performed: returns that Pin's totals over a window, a per-day series, and lifetime totals that ignore the window. Only a Pin this account OWNS can be read; anything else returns 404, including a Pin on a group board this account merely collaborates on. Pinterest itself would report on those, but this endpoint does not — do not retry a shared-board Pin, and do not tell the user the id was wrong. A 403 means Pinterest permanently forbids analytics for that Pin — it will never report, so do not retry it. Reading analytics is free and consumes no credits. pinId is the PINTEREST Pin id, NOT the Tailwind postId that list_posts and get_post return as `id`. Get one from list_top_pins, or from a published post's Pinterest pin id. Passing a Tailwind postId returns a 404. Omit startDate and endDate for the last 30 days; supply BOTH to choose a window (supplying one is an error). Dates are UTC YYYY-MM-DD. Pinterest reports at most 90 days back and at most a 90-day span. The range actually used comes back as startDate/endDate — report those, do not assume the period. If the user did not say which Pinterest account to use and list_accounts returns more than one, ask the user which account to use before calling this — do not choose for them.

get_pin_analytics

Use this to poll a Pin copy generation started by generate_pin_copy. It usually completes in under a minute: poll every ~5 seconds. When status is success, result.pins holds the title and description pairs — offer them to the user, or pass one to create_post. This polls Ghostwriter copy only; generate_pins_from_url generations are polled with get_generation_status instead.

get_copy_generation_status

Use this to 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 — retryable failures can hold processing for several minutes, and a hung generation can stay processing for ~25 minutes before the terminal generation-request-timed-out status appears. A 404 within ~10 seconds of starting the generation is a transient indexing artifact — retry it, don't stop. When status is success, call list_posts with status draft and filter by the matching generationId to find the generated Pins.

get_generation_status

Use this when you already have an accountId and need that one account's details — its username, display name, connection status, or claimed domain — without listing every account. Takes an accountId from list_accounts. Prefer list_accounts when you do not have an accountId yet, or when the user's request could mean any of their accounts. A 404 means the account is not yours or is no longer connected to Tailwind; the message says which. If the user did not say which Pinterest account to use and list_accounts returns more than one, ask the user which account to use before calling this — do not choose for them.

get_account

Use this when the user asks how their Pinterest account is performing overall — impressions, engagement, saves, clicks — or wants a trend over time: returns account-wide totals plus a per-day series. Covers claimed and unclaimed content alike, the same numbers Pinterest Insights shows in Tailwind. This is the account rollup. For the best-performing Pins use list_top_pins; for one Pin use get_pin_analytics. Reading analytics is free and consumes no credits. Omit startDate and endDate for the last 30 days; supply BOTH to choose a window (supplying one is an error). Dates are UTC YYYY-MM-DD. Pinterest reports at most 90 days back and at most a 90-day span. The range actually used comes back as startDate/endDate — report those, do not assume the period. If the user did not say which Pinterest account to use and list_accounts returns more than one, ask the user which account to use before calling this — do not choose for them.

get_account_analytics

Use this when the user asks what is on their Pinterest schedule, when their next opening is, or how full their queue looks: returns the account's schedule over a date window as concrete dated entries, each marked open, scheduled, publishing or published. Unlike list_timeslots — which returns the recurring weekly rules and no occupancy — this shows which specific times are actually free. Read it to answer questions and to reason about the queue. Do NOT read an open entry and then pass its time back as sendAt to schedule a Pin: what is open at read time can be taken by the time the write lands. Pass useNextOpenSlot: true to create_post or schedule_post instead, which resolves and claims a slot in one step. Defaults to the next 14 days from now; from/to accept ISO 8601 datetimes and the window cannot exceed 60 days. If the user did not say which Pinterest account to use and list_accounts returns more than one, ask the user which account to use before calling this — do not choose for them.

get_schedule

Use this when the user asks about one specific Pinterest Pin and a postId is already known (from create_post, schedule_post, or list_posts): returns that single Pin's current status, media, title, description, destination url, board, and scheduled or published time. Reading one Pin by ID is the precise way to confirm what a Pin looks like now — paging list_posts to hunt for it is not. A deleted Pin stays readable with status "deleted" for at least 28 days, after which it becomes eligible for automatic purge; once purged, and for a postId that never existed on this account, the call returns a not-found error. If the user did not say which Pinterest account to use and list_accounts returns more than one, ask the user which account to use before calling this — do not choose for them.

get_post

Use this when the user wants to see their connected Pinterest accounts, or as the first step of any Pinterest Pin workflow: lists the Pinterest accounts connected to the user's Tailwind organization with each account's accountId, username, display name, and connection status. Call this first — every other tool requires an accountId from this list. When more than one account comes back and the user did not say which one to use, ask the user which account to use before acting on any of them — do not choose for them.

list_accounts

Use this when the user wants to see their Pinterest boards, or whenever you need a boardId — this is how to get the boardId values that create_post and schedule_post take. Lists the Pinterest boards on an account (accountId from list_accounts) with each board's numeric ID, name and Pin count. The Pin count comes from a cached snapshot and can lag behind Pinterest, so treat it as a lower bound rather than an exact figure. Board IDs are numeric — never pass a board name or URL where a boardId is expected. If the user did not say which Pinterest account to use and list_accounts returns more than one, ask the user which account to use before calling this — do not choose for them.

list_boards

Use this when the user asks about their board lists, when auditing how their boards are organized, or when they name one of their board lists as where a Pin should go: lists the account's board lists (Tailwind's named groupings of boards, used to publish one Pin to several boards in order). Each list gives its boards in publishing order. To actually publish to a list, read its boards here and pass them as create_post's intervalBoards, keeping this order — the list itself is not a target you can pass anywhere, and a list is a saved grouping that can change, so what you publish to is the boards it holds right now. A board on the account that appears in no list is not covered by any grouping; a list entry whose board id is absent from list_boards points at a board that no longer exists on the account. If the user did not say which Pinterest account to use and list_accounts returns more than one, ask the user which account to use before calling this — do not choose for them.

list_board_lists

Use this when the user asks about the sections on a Pinterest board, or when you need a section ID: lists the sections on a board by boardId (from list_boards). Sections are subdivisions within a single board. Returns an empty list when the board has no sections, which is normal. If the user did not say which Pinterest account to use and list_accounts returns more than one, ask the user which account to use before calling this — do not choose for them.

list_board_sections

Use this when the user wants to see their Pinterest Pins — drafts, scheduled (queued), or published (sent): lists an account's Pins filtered by status (default queued) and returns each Pin's postId for use with get_post, schedule_post and delete_post. Takes an accountId from list_accounts. Results are cursor-paginated; listing sent or uploading Pins requires startDate and endDate. If the user did not say which Pinterest account to use and list_accounts returns more than one, ask the user which account to use before calling this — do not choose for them.

list_posts

Use this when the user wants to see what public Pinterest group boards exist for a topic, or wants benchmark context for how boards in their niche are named and sized. Returns public collaborative boards matching a keyword from Tailwind's Group Board Finder. These are OTHER people's public boards — they are not the user's own boards (use list_boards for those), and their board ids cannot be passed to create_post or schedule_post. Results are cached and refreshed in the background, so check `status` before reporting: `ready` means the boards returned are what we have (an empty list means a completed search genuinely found none), `warming` means a search is still running and you should tell the user to check back rather than reporting no results, and `unavailable` means the search failed and no benchmark data can be given for this keyword.

list_group_boards

Use this when the user asks what keywords they have saved, or when you need their own keyword list to write Pin titles and descriptions, pick a board topic, or plan content. Returns the organization's Saved Keywords list from Tailwind — terms the user has already chosen to track. This is NOT keyword research: it will not discover new keywords or report how a term is trending, it only reads back what is already on their list. Results are paginated newest-first; pass the returned nextCursor to read further.

list_saved_keywords

Use this when the user asks what their posting schedule looks like, or which times Tailwind recommends: lists the account's smart schedule timeslots. Each slot is a RECURRING WEEKLY time (day of week + HH:MM + timezone), not a concrete date, and this read says nothing about which upcoming occurrences are already taken — use get_schedule for that, which returns dated entries marked open or occupied. This is a read for showing or explaining the recurring schedule; it is NOT the way to schedule a Pin into it. To place a Pin on the schedule, pass useNextOpenSlot: true to create_post or schedule_post: that resolves the next genuinely open slot and applies the account's Pin Spacing rules for the Pin's destination url. Do not compute an occurrence from these slots and pass it as sendAt — that ignores which slots are occupied and ignores Pin Spacing, so Pins stack up and land off-schedule. If the user did not say which Pinterest account to use and list_accounts returns more than one, ask the user which account to use before calling this — do not choose for them.

list_timeslots

Use this when the user asks which of their Pins are doing best, what is working, or wants their top performers: returns the account's best Pins over a window, in Pinterest's own ranked order. Ranks by ENGAGEMENT unless sortBy says otherwise, and tells you which metric it used — say so when reporting, since "top" means nothing without it. Only these five metrics rank: ENGAGEMENT, SAVE, IMPRESSION, OUTBOUND_CLICK, PIN_CLICK. This is also how you get a Pinterest pinId to pass to get_pin_analytics. Do not re-sort the results — the order returned IS the ranking. Reading analytics is free and consumes no credits. Omit startDate and endDate for the last 30 days; supply BOTH to choose a window (supplying one is an error). Dates are UTC YYYY-MM-DD. Pinterest reports at most 90 days back and at most a 90-day span. The range actually used comes back as startDate/endDate — report those, do not assume the period. If the user did not say which Pinterest account to use and list_accounts returns more than one, ask the user which account to use before calling this — do not choose for them.

list_top_pins

Use this when the user asks what Pins they should add to a board, how to fill a gap on a board, or wants content ideas for a board and keyword. Searches Pinterest's public content for Pins matching the keyword, drops any the board already has and any promoted/ad content, and returns what is left ranked strongest first, each with its own relevance as the reason it fits. Free — this spends no plan credits, unlike get_board_keyword_relevance. Pairs with that tool: score the board first to find a weak keyword, then call this to fix it. These are candidates from across Pinterest, not the user's own Pins, so present them as suggestions to review rather than as content they already own — creating a Pin from one still needs create_post. An empty list means nothing on-topic was found for that keyword, not that the board is bad. If the user did not say which Pinterest account to use and list_accounts returns more than one, ask the user which account to use before calling this — do not choose for them.

get_recommended_pins

Use this when the user asks to save, add, or track keywords, or agrees to add terms you suggested. Adds keywords to the organization's Saved Keywords list in Tailwind — the same list the dashboard shows. Matching is case-insensitive, so re-sending a term already on the list returns the stored one rather than creating a duplicate; the response is the saved state of every term you sent, whether new or pre-existing. Saving keywords is free and does not consume credits. Do not call this to look keywords up — use list_saved_keywords for that.

save_keywords

Use this when the user wants to schedule or reschedule an existing Pinterest Pin draft or queued Pin: takes the postId of an existing Pin (from create_post or list_posts) plus exactly ONE of useNextOpenSlot: true or an ISO 8601 sendAt. Prefer useNextOpenSlot whenever the user has not named a specific time — it places the Pin in the account's next open smart schedule slot and applies the account's Pin Spacing rules for the Pin's destination url, which a timestamp you compute yourself cannot. Reserve sendAt for a time the user actually asked for. The Pin must already have title, description, and url set; a draft without a board also needs boardId (numeric ID from list_boards). Pass boardSectionId to schedule it into a Board section — and note that passing boardId on its own clears any section the Pin already had, since a section is only valid on its own Board. Does not work on published Pins. Moving a draft onto the schedule is the charged step: one Pin credit on modular billing with Publishing access, whether subscribed or granted, though winback plans schedule without charge and modular accounts without Publishing draw on a free-trial allowance; legacy and Shopify accounts spend no credits and count it against the plan's post limit instead. Rescheduling a Pin that is already queued costs nothing on any of them. To create and schedule a new Pin in one step, use create_post instead. If the user did not say which Pinterest account to use and list_accounts returns more than one, ask the user which account to use before calling this — do not choose for them.

schedule_post

Use this when the user asks how well one of their boards covers a keyword or topic, or when auditing whether a board is on-topic. Scores a board's own live Pinterest content against a keyword and returns the Pins that earned the score, each with its own relevance. This reads the board's real Pins from Pinterest, not just what Tailwind scheduled to it, so it covers Pins added outside Tailwind too. Metered: each scored call spends one plan credit, so score the board once and reuse the result rather than re-calling per question. A board that returns state "absent" yielded no readable Pins — it is empty, or the Pinterest connection needs reconnecting — and is not charged; report that as unknown coverage, never as poor coverage. Large boards are scored from a capped sample; when truncated is true say the score covers part of the board. If the user did not say which Pinterest account to use and list_accounts returns more than one, ask the user which account to use before calling this — do not choose for them.

get_board_keyword_relevance

Use this when the user wants to change an existing Pinterest Pin's copy — its title, description, destination link, board, Board section, alt text, or product tags — on a draft or a scheduled (queued) Pin, by postId (from create_post, list_posts or get_post). Supply at least one of title, description, url, boardId, boardSectionId, altText or productTagPinIds — a call with only accountId and postId is rejected. Use productTagPinIds to tag catalog products on a Pin that was created without them, to change which products it tags, or — with an empty array — to remove its tags; there is no need to delete and recreate the Pin for any of that. Moving the Pin with boardId alone clears any Board section it was in, because a section is only valid on its own Board: pass boardSectionId as well to land it in a section of the new Board, or "" to put it at the Board root. Only the fields you send are changed; everything else is left as it is. Editing is free and does not consume a credit. This does NOT schedule or reschedule: use schedule_post for that, and note the Pin's image cannot be changed at all — that needs a delete_post plus a fresh create_post. A Pin already published to Pinterest cannot be edited through Tailwind; the user has to edit it in the Pinterest app. If the user did not say which Pinterest account to use and list_accounts returns more than one, ask the user which account to use before calling this — do not choose for them.

update_post

Use this when the user wants to rename a Pinterest board or change its description: updates an existing board by boardId (from list_boards). Boards marked as collaborator entries in list_boards belong to someone else — the account can pin to them but cannot rename them, so do not pass those IDs here. Supply at least one of name or description; anything you omit is left as it is. A board's privacy cannot be changed here — flipping a public board to secret would hide every Pin on it from everyone but the owner. If the user did not say which Pinterest account to use and list_accounts returns more than one, ask the user which account to use before calling this — do not choose for them.

update_board

Use this when the user wants to rename a section on a Pinterest board: renames a section by sectionId (from list_board_sections) on a board by boardId (from list_boards). If the user did not say which Pinterest account to use and list_accounts returns more than one, ask the user which account to use before calling this — do not choose for them.

update_board_section