PickFu Market Research#

Get real human feedback on anything — logos, names, packaging, pricing, ads, UX, book covers, Amazon listings, and more. This skill runs end-to-end consumer research: brief → design → create → publish → wait → analyze → iterate.

Capabilities#

This skill can:

• Generate images — create logo concepts, packaging mockups, ad creatives for testing
• Upload media — upload local files or URLs to PickFu's CDN for use in surveys
• Design multi-question surveys — 10 question types (A/B, ranked, open-ended, star rating, click test, etc.)
• Target specific audiences — demographics, Amazon Prime members, iOS/Android users, by country
• Create, publish, and monitor surveys — full lifecycle management
• Analyze results — structured reports with verbatim quotes and demographic breakdowns
• Tag and organize — tag surveys, group into projects
• Add respondents — boost sample size on completed surveys
• Search past surveys — find and reference previous research
• Iterate on creative concepts — generate → test → refine → retest loop
• Browse playbook templates — pre-built research workflows for common use cases

Step 0 — Connect to PickFu#

0a. Try MCP tools first#

Call list_available_targeting (read-only). If it succeeds, MCP is connected — use MCP tools for all API calls.

0b. CLI fallback#

If MCP is unavailable, use the PickFu CLI. Check auth:

bash

npx --yes @pickfu/cli@latest auth status --json

If authenticated, proceed.

0c. New user setup#

If not authenticated, guide the user:

Option 1 — API key (recommended for agents): Tell the user to get a key at app.pickfu.com/settings/api-keys, then:

bash

export PICKFU_API_KEY=sk_...

Option 2 — OAuth (interactive):

bash

npx --yes @pickfu/cli@latest auth login --headless

Show the printed URL to the user and wait for the command to complete. The user clicks the URL, authenticates in their browser, and the CLI catches the callback automatically.

Visit agents.pickfu.com for additional install options.

0d. Discover available commands#

Run this once per session to learn all available CLI commands and their parameters:

bash

npx --yes @pickfu/cli@latest schema

This returns every command, flag, description, and output schema — use it to discover capabilities not explicitly documented here.

Important: All API fields use camelCase (e.g., mediaUrl, sampleSize, surveyIntent, imageSet). Never use snake_case.

Step 1 — Research Brief#

Capture the research objective. Ask:

1. What decision are you trying to make?
2. Product/context — what's the product or category?
3. Target audience — who should answer?
4. Hypotheses — any hunches, or purely exploratory?
5. Constraints — budget, timeline, country?

Step 2 (optional) — Generate Test Assets#

If the user needs images but doesn't have them:

CLI: npx --yes @pickfu/cli@latest media generate --prompt "..." --aspect-ratio 1:1 --json MCP: Call generate_image with prompt and optional aspectRatio

The response includes a url — use it as a mediaUrl option in the survey. Generate multiple variations with different prompts to test against each other.

To upload existing files: npx --yes @pickfu/cli@latest media upload --file ./logo.png --json or --url https://...

Brand-faithful variants from a reference image#

If the user has an existing image (their current logo, packaging, or product shot) and wants variants that preserve brand identity (typography, color, mascot, layout) while changing one specific dimension, pass the reference:

CLI: npx --yes @pickfu/cli@latest media generate --prompt "..." --reference-image-url https://... --aspect-ratio 1:1 --json

Use one variant per testable hypothesis (e.g., "stronger contrast", "removes peanut illustration", "adds protein callout") and print the hypothesis alongside each generated URL so the eventual survey result can be tied back to the design choice. Without a reference image, generated variants tend to hallucinate brand details (misspelled wordmarks, invented URLs, wrong mascot poses).

Step 3 — Survey Design#

Best practices#

• One question, one concept — don't combine two questions into one
• Neutral, non-leading prompts — "Which do you prefer?" not "Which looks more professional?"
• Match type to goal — head_to_head for A/B, ranked for ordering 3+, open_ended for exploratory
• Keep it short — 1-3 questions ideal, 5+ risks fatigue
• Use images when possible — visual options get more engaged responses
• Be specific — "Which would you click in search results?" beats "Which do you like?"

Question types#

TypeBest forOptionshead_to_headA/B comparisonExactly 2rankedPreference ordering3-8open_endedFree-form feedback0-1single_selectPick one favorite3-8multi_selectSelect multiple3-8emoji_ratingQuick sentiment0-1star_rating1-5 stars + feedback0-1click_testHeatmap clicks1 (image)five_second_testFirst impressions1 (image)screen_recordingUser interaction0-1

Targeting and reporting#

Discover available options:

• CLI: npx --yes @pickfu/cli@latest targeting list --json and reporting list --json
• MCP: Call list_available_targeting and list_available_reporting

Sample sizes#

15 (quick signal), 30-50 (standard), 100 (high confidence), 200-500 (large-scale validation)

Countries#

US (default), CA, AU, DE, GB, JP, MX, ES, FR, IT, KR, BR, ZA, PL

Present the full design to the user for approval before creating.

Step 4 — Create & Publish#

Create#

MCP: Call save_survey (omit surveyId to create new)

CLI: Write survey JSON to a temp file:

bash

cat > /tmp/survey.json << 'EOF'
{
  "surveyIntent": "Which logo do pet owners prefer?",
  "sampleSize": "50",
  "country": "US",
  "targeting": ["amznpr"],
  "reporting": ["gender", "age-range"],
  "questions": [{
    "type": "head_to_head",
    "prompt": "Which logo do you prefer for a pet food brand?",
    "options": [
      { "mediaUrl": "https://cdn.example.com/logo-a.jpg" },
      { "mediaUrl": "https://cdn.example.com/logo-b.jpg" }
    ]
  }]
}
EOF
npx --yes @pickfu/cli@latest survey create --from-file /tmp/survey.json --json

Confirm before publishing#

⚠️ Publishing charges the user's account and starts data collection. Always ask for explicit confirmation.

Publish#

MCP: Call publish_survey with the survey id CLI: npx --yes @pickfu/cli@latest survey publish <id> --json

Step 5 — Wait for Results#

Poll until .status == "done":

CLI (preferred for agents):

bash

until npx --yes @pickfu/cli@latest survey get <id> --json | jq -e '.status == "done"' >/dev/null; do
  sleep 60
done

MCP: Call get_survey with the survey id in a loop until status === "done".

Sample sizes of n=15 general typically complete in 20–30 minutes; n=50+ or heavy targeting can take several hours. If still not done after 4 hours, stop polling and surface a clear error — something is wrong (paused, no panel inventory, etc.).

Avoid survey watch in agent harnesses. It blocks at the process level and runs forever, which works for a human in a terminal but breaks in runtimes that cap individual command duration (Claude Code's Bash tool cuts single commands at 10 min). The polling loop above resets that clock every iteration.

Step 6 — Analyze & Report#

Retrieve results:

• MCP: get_survey + get_survey_responses
• CLI: survey get <id> --json + survey responses <id> --json

Generate a structured report:

markdown

## Research Report

### Executive Summary
[2-3 sentences: key finding, winner, confidence]

### Survey Details
- **Survey**: [URL: https://www.pickfu.com/surveys/<id>]
- **Respondents**: [N] from [country], targeting: [traits]

### Per-Question Analysis
#### Q1: [prompt] ([type])
**Result**: [winner/ranking/rating]
**Distribution**: [breakdown]
**Notable Quotes**:
> "[verbatim quote]" — [demographic]

### Demographic Breakdown
| Segment | Option A | Option B |
|---------|----------|----------|

### Next Steps
- [Recommendation]
- [Follow-up research suggestion]

Report guidelines#

• Always include the survey URL — users need it for the full dashboard
• Quote real respondent feedback — verbatim quotes are the most valuable output
• Be direct about the winner — don't hedge when data is clear
• Highlight demographic differences if reporting was configured
• Suggest follow-up research when results raise new questions

Step 7 (optional) — Organize & Iterate#

⚠️ Survey update safety: When using survey update, only include the fields you want to change. Do NOT include questions unless you intend to modify them — if you send questions without option IDs, the API will delete and recreate all questions, losing image attachments. Tags, project, name, sampleSize, and country can all be updated independently without affecting questions.

Tag surveys#

Attach tags via survey update (creates tags automatically if they don't exist):

MCP: Call save_survey with surveyId and tags: [{"name": "..."}] CLI:

bash

echo '{"tags": [{"name": "q2-launch"}, {"name": "logo-testing"}]}' | \
  npx --yes @pickfu/cli@latest survey update <id> --from-file /dev/stdin --json

Note: tags is a replace-all operation — include all desired tags each time.

Assign to project#

MCP: Call save_survey with surveyId and projectId CLI:

bash

npx --yes @pickfu/cli@latest project create --name "Brand Launch" --json
echo '{"projectId": "<id>"}' | npx --yes @pickfu/cli@latest survey update <survey-id> --from-file /dev/stdin --json

Add more respondents#

CLI: npx --yes @pickfu/cli@latest survey add-respondents <id> --count 50 --preview --json (preview first, then without --preview to commit)

Search past surveys#

CLI: npx --yes @pickfu/cli@latest survey list --tag "logo-testing" --status completed --json

Creative iteration loop#

After results: review feedback → generate refined options → run follow-up survey → repeat until winner is clear.

Error Handling#

ErrorActionNot authenticatedGuide user through Step 0cPICKFU_API_KEY invalid"Generate a new key at app.pickfu.com/settings/api-keys"MCP auth expiredGuide user to reconfigure MCP server auth tokenInsufficient balance"Add funds at app.pickfu.com/settings/credits"head_to_head requires 2 optionsFix option countranked requires 3-8 optionsAdjust to 3-8prompt max 255 charactersShorten question textURL must use httpsReplace http with httpsUnknown field ignoredCheck camelCase — all fields are camelCase (mediaUrl, sampleSize, etc.)

For more help: pickfu.com/help | pickfu.com/docs