PickFu runs polls and surveys with real, targeted consumer panels so you can test decisions before you commit. Ask a question — compare two product images, headlines, logos, app icons, or names — and get ranked results with written explanations from real people in the demographic you choose, usually within minutes. Build a poll, launch it to a targeted audience, and read the results (the winner, the vote breakdown, and respondents' comments) without leaving the chat. Built for marketers, founders, designers, and product teams who want evidence instead of guesses.
generate_image first and pass its returned image_url as mockup.image. For a survey with image options, pass previewImages: true to also get an inline preview of every image, labeled by question/option — show those to the user so they can confirm the correct assets are attached (and catch mistakes like two options sharing the same image) before launching. Pass questions as a FLAT array of { type, prompt, options } objects — do not double-nest it. Each option uses exactly ONE content type (value OR mediaUrl OR asin OR imageSet OR mockup). Example: { questions: [{ type: "head_to_head", prompt: "Which do you prefer?", options: [{ value: "A" }, { value: "B" }] }], targeting: ["amznpr"] }.read scope; the caller must be able to view the survey. Use the format argument to limit which formats are returned, and the language argument (ISO 639-1 code) to filter PDF/PNG entries by language. CSV URLs include a short-lived signed token that lets MCP clients follow the link without supplying their own auth header. URLs are returned as resource_link content blocks the client can download or render directly.image_url as mockup.image in save_survey or build_poll_url. Describe the image in the prompt, and optionally provide up to 3 existing reference images to adapt. For local files, call upload_media with no arguments to mint a PickFu upload link, then check_upload for media-cdn.pickfu.com URLs. Generating images is free — do not tell the user it costs anything. Uses Nano Banana Pro and returns the generated image URL in image_url.steps_markdown — a markdown guide whose steps contain pre-filled survey-creation URLs for the user to open (these links are user-facing, not inputs for save_survey).language selects stored translations; if the requested language is unavailable, the API returns the available languages instead of silently returning untranslated content. Each question includes a results summary with the final outcome — per-option vote counts, percentages, and ranking (winner first), matching the numbers on the results page; for ranked questions these reflect the human panel's final instant-runoff (IRV) round, not first-choice share. Compare with get_synthetic_feedback_results only after aligning the question, option identities, and audience; label each source and metric separately. Do not pool human and synthetic samples or treat their percentages as equivalent. results is null for open_ended, click_test, likert, five_second_test, and screen_recording, or before any responses arrive; emoji_rating/star_rating return an averageScore instead of per-option votes. For surveys with many responses, use get_survey_responses for pagination.language selects stored translated response explanations; if the requested language is unavailable, the API returns the available languages instead of silently returning untranslated content. Supports filtering by keyword (text) and respondent demographics (traits). When page is omitted, auto-fetches all pages (limit is ignored in this mode). Use get_survey for metadata and AI summaries. Use list_available_targeting for trait permalink values. To flag a specific response as helpful or not_helpful, pass its id to rate_response. Each response includes a pinned field — use pin_response to pin or unpin responses.summary with winner (the option the twins leaned toward, or null when the top options tied), options (each option's label and content), sampleReasons (short per-option quotes), and usually a narrative paragraph. Lead with the narrative: the themes behind the result, then which options fell in the stronger half and which in the weaker half. Without a narrative, give the direction from winner and sampleReasons. A null winner means the twins split evenly: say so, and do not pick a side. The summary carries no vote counts, percentages or mean ranks, on purpose: twins converge, so a synthetic margin overstates the real one. Never state, estimate or tally vote shares, vote counts, mean ranks or margins for a synthetic result, and never crown a winner with a margin. If the user needs the size of the gap, recommend a human survey. To set a synthetic result beside a human survey from get_survey, first align the question, option identities and audience, then compare direction only and label each source. Do not pool human and synthetic samples. Single-concept open-ended requests return a summary with the panel's themes and quotes for the one question asked. By default (individualAnswers omitted or false) you get only that summary. AFTER presenting it, you MUST tell the user they can drill into the raw per-respondent answers. If they say yes, call this tool again with the same guid and individualAnswers: true — that returns results (per-respondent Q&A, keyed by short anonymous segment_name ids) in place of summary. For a comparison, each answer is one twin's pick and reason: quote the reasons, but do not count the picks into shares. Do not return both in a single call. If the response has summary_status: "unavailable" (no summary field, no results field), the summary failed to generate for this run. Tell the user the summary is not available, then offer to fetch the per-respondent answers instead — if they say yes, call this tool again with the same guid and individualAnswers: true. Respondent ids quoted in an open-ended summary (respondent_id) match the segment_name strings in results, so quotes can be cross-referenced once the user asks for the drill-down. If a response carries next_step, it overrides the resume rule above: the run is still in progress and this turn is nearly out of time. Tell the user it is still running, and do not call this tool again in the same turn.id, a user-facing title, and a description. Present the titles and descriptions to the user and ask which one they want to run. • Call again with playbook_id set to a listed id to FETCH that playbook's full instructions. STOP after this call: show the playbook to the user and get their explicit confirmation before you begin executing any of its steps. Do not chain straight into running the playbook without that approval. This is distinct from get_playbook/list_playbooks, which serve generic survey-sequence guides — use get_synthetic_playbook for the synthetic-research workflows.mine: true to restrict results to surveys created by the authenticated user. Returns survey metadata including name, status, type, sample size, response count, creator name, tags, projects, and a url field linking to the full results page.subcategory set to one name from the index: it returns that subcategory's synthetic audiences, each with its display name, slug, and a one-line description of its people. Use it when the user wants to see or change which synthetic audience answers their research. get_synthetic_feedback already suggests one automatically, so call this when the user wants a different one, or after a NO_MATCHING_PANEL response whose reason is no_matching_audience, audience_too_specific or unclear_brief, or that gives no reason. Present the choices to the user, let them choose, then call get_synthetic_feedback with the chosen slug as panel to create a new draft. Present that draft and obtain fresh approval before submitting; never change the audience while submitting an existing draft. When presenting the index in Slack or another chat client, preserve one Markdown bullet per subcategory on its own line; never combine subcategories with · separators.status filter to scope to DRAFT / IN_PROGRESS / COMPLETE; default limit is 50 (max 100).previewImages: true (or extract_images on the option image URLs) and show them the labeled previews, since a wrong or duplicated image cannot be fixed once the survey is live.get_survey_responses to programmatically curate response quality — e.g. flag low-effort or off-topic responses for downstream filtering. IMPORTANT: rating a response 'not_helpful' is destructive. It counts against a 10-flag-per-survey cap (returns an error when exceeded) and, when within the cap, auto-rejects the response (and, on multi-question surveys, all responses from the same respondent), recalculates the survey's valid-answer count, and may reopen a completed survey to collect replacement responses. Confirm with the user before applying 'not_helpful' to multiple responses in bulk. Switching a previous 'not_helpful' rating to 'helpful' records the new vote but does NOT un-reject the response that was auto-rejected by the prior flag. Re-rating without re-sending the comment field preserves the previous comment.completionEstimate object when the feature is enabled: bucket (SUPER_EASY, EASY, MEDIUM, HARD, or MAY_NOT_COMPLETE), estimatedMinutes (number or null), and status ('ready' or 'pending'). This reflects how quickly the selected audience is expected to fill. If bucket is MAY_NOT_COMPLETE, warn the user that the audience is too narrow and suggest broadening it. For sampleSize 5, 10, 20, or 25, include questions containing a screen_recording question, even on updates. Use get_survey to retrieve the existing questions and preserve their ids; without questions, only standard sample sizes (15, 30, 50, 75, 100, 200, 300, 500) are accepted. LIKERT: Use 2–8 text statements as options[].value, no media or URLs. The likertScale presets are agreement5, agreement7, frequency, satisfaction; agreement5 is the default on create, and omitting likertScale on an update preserves the question's existing scale rather than resetting it. TEMPLATES: to run a template (a ready-made single-question poll at a fixed price per respondent), call get_template first to read its question, blanks, option slots and limits, then create with template: { id, blanks?, prompt?, context?, options? } in place of questions. Template ids start with cmb_ and come from list_templates. Fill every {{name}} blank through blanks, keyed by its name; use prompt only on a template without blanks. Omitted name, sampleSize, country and targeting come from the template; targeting replaces the preset audience, so to change it send the template's preset traits plus your additions. reporting cannot be sent because a template's reporting traits are fixed. A draft outside the template's limits is rejected with every violation and its allowed values, and nothing is saved: fix each one and retry, or build the poll with questions at standard pricing. Template is create only; edit the draft afterwards with surveyId and questions. Create or update a PickFu survey. Omit surveyId to create; include surveyId to update. When updating questions, include 'id' fields (from get_survey) to update in-place — questions/options without 'id' are created as new, and those missing from the payload are removed. IMPORTANT: every response automatically includes a required written explanation from the respondent for every question type except screen_recording. Do NOT add a separate open_ended question to capture 'why' — it duplicates the built-in explanation and wastes a question slot (multi-question surveys are priced per question). Phrase the real question, and the explanation comes back on each response as the explanation field. The response includes a cost object with: amount (dollars), balance (dollars), currency, canPayWithBalance, quotedCreditsCost (post-discount credits after free credits), creditsCostSubtotal (pre-discount credits), discounts (credit-side [label, amountInCredits] tuples — amounts are in credits, 1 credit = $2, and subtract directly from creditsCostSubtotal), discountsMoney (dollar-side [label, '$X.XX'] tuples), and planRequired (plan tier name or null). Note: Some reporting traits are auto-injected as free defaults based on the user's plan (Basic plans: age-range, gender; Standard+ plans: age-range, gender, ethnicity, house-income, edu). The response includes a reportingDefaultsApplied array listing which traits were auto-added vs explicitly requested. OPTION SHAPE: each option carries exactly ONE content type — text (value), image/video (mediaUrl), Amazon product (asin), multiple images (imageSet), or a custom listing (mockup). Never combine them on one option; an image option is NOT given a text label (respondents see A, B, C…). For a hypothetical/custom mockup without an image, call generate_image first and pass its returned image_url as mockup.image. The one exception is a mockup template such as an App Store page: call list_mockup_templates, then give every option of the question { value, mockup: { template, values } }. When the template lists importSources, send `mockup.i…guid; audience changes require a new get_synthetic_feedback draft and a new approval. Optionally pass questions when the user edited the question text (single-concept research has exactly one question). Optionally pass excludePollGuids when the request repeats existing PickFu surveys, for example in a benchmark replay. The response confirms dispatch with the request guid and status; present that confirmation, then call get_synthetic_feedback_results once with the same guid to retrieve the completed prediction. That call streams live progress and returns when the panel is COMPLETE (typically a few minutes). Do not call it repeatedly. Cost: free for this account until PickFu's new plans launch. If asked about future prices, point to https://www.pickfu.com/help/what-do-platform-credits-cost rather than quoting one.url; (2) pass base64 data (images only — JPEG/PNG/GIF/WebP/BMP/TIFF/SVG, max 20 MB; videos must use url) — ONLY when the file exists on local disk you can read directly (CLI/IDE clients such as Claude Code or Cursor); (3) call with neither url nor data to mint a PickFu-hosted upload session. If the user ATTACHED the file in the chat, always use mode 3: chat attachments are not reliably accessible as raw bytes, and re-encoding or compressing them into base64 tool calls fails on payload limits — do not attempt it. Present the returned upload_url to the user, wait for them to return, then call check_upload with the returned token to receive ordered media-cdn.pickfu.com URLs and continue the original task. YouTube/Vimeo/Wistia URLs do not need uploading.
