PickFu Market Research

Run consumer research surveys with PickFu to get real human feedback in minutes — generate images, validate product names, compare logos and packaging, test...

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:

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:

export PICKFU_API_KEY=sk_...

Option 2 — OAuth (interactive):

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:

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://...

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

Type	Best for	Options
head_to_head	A/B comparison	Exactly 2
ranked	Preference ordering	3-8
open_ended	Free-form feedback	0-1
single_select	Pick one favorite	3-8
multi_select	Select multiple	3-8
emoji_rating	Quick sentiment	0-1
star_rating	1-5 stars + feedback	0-1
click_test	Heatmap clicks	1 (image)
five_second_test	First impressions	1 (image)
screen_recording	User interaction	0-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:

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 complete:

CLI: npx --yes @pickfu/cli@latest survey get <id> --json | jq '{status, responses_count}' MCP: Call get_survey with the survey id

Poll every 60 seconds. After 30 minutes, offer to check back later.

Alternative (zero token cost): npx --yes @pickfu/cli@latest survey watch <id> --json — blocks at process level, but may timeout in some runtimes.

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:

## 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:

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:

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

Error	Action
Not authenticated	Guide user through Step 0c
PICKFU_API_KEY invalid	"Generate a new key at app.pickfu.com/settings/api-keys"
MCP auth expired	Guide user to reconfigure MCP server auth token
Insufficient balance	"Add funds at app.pickfu.com/settings/credits"
head_to_head requires 2 options	Fix option count
ranked requires 3-8 options	Adjust to 3-8
prompt max 255 characters	Shorten question text
URL must use https	Replace http with https
Unknown field ignored	Check camelCase — all fields are camelCase (mediaUrl, sampleSize, etc.)

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