@50heads/mcp 2026.925.1

package/dist/types/server.d.ts

@@ -0,0 +1,71 @@
+import { McpServer, type ServerContext } from "@modelcontextprotocol/server";
+import { type Client } from "@50heads/shared/client";
+export { MCP_RESOURCE_URL, PROMPT_SCOPES, PUBLIC_RESOURCE_PREFIXES, SERVER_NAME, SERVER_VERSION, TOOL_NAMES, TOOL_SCOPES, resourceScope, type ToolName, } from "./constants.js";
+export type CallLog = {
+    kind: "tool" | "resource" | "prompt";
+    name: string;
+    questionId?: string;
+    outcome: "ok" | "input_required" | string;
+    latencyMs: number;
+};
+export type Era = "modern" | "legacy";
+export type ServerOptions = {
+    /** A typed API client for the calling principal, tagged with what it serves (for logs). */
+    api: (tool: string) => Client;
+    /** 2026-07-28 (per-request envelope) or 2025-11-25 (initialize handshake). */
+    era: Era;
+    /** Stable id of the caller for idempotency derivation (connection id or token hash). */
+    principal: string;
+    /** Granted scopes; null when unknown (the API enforces them). */
+    scopes: readonly string[] | null;
+    /** False when the request carried no token (only public tools and resources work). */
+    authenticated: boolean;
+    portalUrl: string;
+    webUrl: string;
+    /** Protected resource metadata URL, advertised in the com.50heads/auth extension. */
+    resourceMetadataUrl?: string;
+    traceId?: string;
+    /** Longest a single call may block (wait_for_results), in ms. Default 600 s. */
+    maxWaitMs?: number;
+    onCall?: (log: CallLog) => void;
+    /** Fetches public files from webUrl (the help index for search_help). Default: global fetch. */
+    fetchWeb?: typeof fetch;
+    /** Sent with feedback so support can tell hosts and versions apart, such as "mcp/2026.924.1". */
+    source?: string;
+};
+/** The extensions the server declares (server/discover and initialize). */
+export declare function serverExtensions(opts: Pick<ServerOptions, "resourceMetadataUrl" | "webUrl">): {
+    "io.modelcontextprotocol/tasks": {
+        methods: string[];
+        tools: string[];
+        pollIntervalMs: number;
+    };
+    "io.modelcontextprotocol/apps": {
+        mimeTypes: string[];
+        views: string[];
+    };
+    "com.50heads/skills": {
+        skillVersion: string;
+        skills: {
+            name: string;
+            version: string;
+            uri: string;
+            files: string[];
+            download: string;
+        }[];
+    };
+    "com.50heads/auth": {
+        authorizationServer: string;
+        apiKeys: string;
+        resourceMetadata?: string | undefined;
+    };
+};
+export declare const INSTRUCTIONS: string;
+export declare function clientName(ctx: ServerContext): string | undefined;
+/** Creates the 50heads MCP server for one request (HTTP) or one connection (stdio). */
+export declare function createServer(opts: ServerOptions): McpServer;
+/**
+ * A first draft from a goal and assets: two image URLs make an A or B question; listed
+ * options make a single choice; otherwise a yes, mostly or no check. The model refines it.
+ */
+export declare function draftFromGoal(goal: string, assets?: string): Record<string, unknown>;

package/dist/types/snippets.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Config snippets per host: the one source for install instructions. Printed by
+ * `npx @50heads/mcp config`, written into README.md by scripts/generate.ts, and rendered by the
+ * website's MCP docs page and For agents page (apps/web imports @50heads/mcp/snippets).
+ * Hosted URL plus OAuth for the hosts that support it; the npx line for the rest.
+ */
+export declare const CLIENTS: readonly ["claude-desktop", "claude-code", "cursor", "chatgpt", "vscode", "windsurf", "generic"];
+export type ClientId = (typeof CLIENTS)[number];
+export type SnippetOptions = {
+    /** The hosted endpoint. */
+    url?: string;
+    /** An API key to show, or the placeholder. */
+    apiKey?: string;
+};
+export type Snippet = {
+    client: ClientId;
+    title: string;
+    /** Where the snippet goes, in a sentence. */
+    where: string;
+    /** "oauth": the hosted URL with a browser sign-in. "key": the npx line with an API key. */
+    auth: "oauth" | "key";
+    format: "json" | "shell" | "text";
+    body: string;
+    /** A second way in, when the host offers one. */
+    alternative?: {
+        where: string;
+        format: "json" | "shell";
+        body: string;
+    };
+};
+export declare function configSnippets(options?: SnippetOptions): Snippet[];

package/dist/types/tasks.d.ts

@@ -0,0 +1,87 @@
+import type { QuestionV2 } from "@50heads/shared";
+import type { Client } from "@50heads/shared/client";
+import type { Currency } from "./pricing.js";
+/**
+ * Tasks (io.modelcontextprotocol/tasks): a fifty-answer question is a long-running operation.
+ * `ask` returns a task whose id is the question_id, so the task state lives in the API and a
+ * results object stays fetchable for ever after the task is gone. The server keeps nothing.
+ *
+ * Methods: tasks/get (progress, and the results once done), tasks/update (min_answers to
+ * complete early), tasks/cancel (maps to cancel), and tasks/result for 2025-11-25 clients.
+ * There is no tasks/list.
+ */
+export declare const TASKS_EXTENSION = "io.modelcontextprotocol/tasks";
+export declare const TASK_POLL_INTERVAL_MS = 5000;
+export declare const TASK_METHODS: readonly ["tasks/get", "tasks/update", "tasks/cancel", "tasks/result", "tasks/list"];
+export type TaskMethod = (typeof TASK_METHODS)[number];
+export declare function isTaskMethod(method: unknown): method is TaskMethod;
+/** The scope each task method needs (spec: questions:read for tasks/get, write for cancel). */
+export declare const TASK_SCOPES: Record<TaskMethod, string | null>;
+export type TaskStatus = "working" | "input_required" | "completed" | "failed" | "cancelled";
+export type TaskObject = {
+    taskId: string;
+    /** The 2026-07-28 extension names it `id`; 2025-11-25 names it `taskId`. Same value. */
+    id: string;
+    status: TaskStatus;
+    statusMessage: string;
+    createdAt: string;
+    lastUpdatedAt: string;
+    /** Results are kept for ever; the task handle never expires. */
+    ttl: null;
+    pollInterval: number;
+};
+export declare function isTerminal(status: TaskStatus): boolean;
+/** "12 of 50 answered · about 6 minutes left" */
+export declare function statusMessage(q: Pick<QuestionV2, "status" | "answered" | "n" | "etaMinutes" | "refusedCategory">): string;
+export declare function toTask(q: QuestionV2, now?: string): TaskObject;
+export type TaskDeps = {
+    /** A client for the calling principal, tagged with the task method. */
+    api: (method: string) => Client;
+    portalUrl: string;
+    /** Overrides the account's display currency; by default it is read from the balance. */
+    currency?: Currency;
+    traceId?: string;
+    /** Aborts the tasks/result long-poll when the caller goes away. */
+    signal?: AbortSignal;
+    /** Longest tasks/result waits, in ms (the HTTP host's request budget). */
+    maxWaitMs?: number;
+};
+type RpcRequest = {
+    jsonrpc: "2.0";
+    id: string | number;
+    method: string;
+    params?: Record<string, unknown>;
+};
+type RpcResponse = {
+    jsonrpc: "2.0";
+    id: string | number;
+    result: Record<string, unknown>;
+} | {
+    jsonrpc: "2.0";
+    id: string | number;
+    error: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+};
+/** True when the request carries the 2026-07-28 per-request envelope. */
+export declare function isModernMessage(msg: {
+    params?: Record<string, unknown>;
+}): boolean;
+/**
+ * Serves one tasks/* JSON-RPC request end to end (the SDK has no task runtime for the
+ * 2026-07-28 extension, so the HTTP edge and the stdio transport both route here).
+ */
+export declare function serveTaskMessage(msg: RpcRequest, deps: TaskDeps & {
+    serverInfo: {
+        name: string;
+        version: string;
+    };
+}): Promise<RpcResponse>;
+/**
+ * Serves one tasks/* request. Throws McpToolError (not_found → -32602, and so on); an unknown
+ * method or tasks/list throws a -32601.
+ */
+export declare function handleTaskRequest(method: string, rawParams: unknown, deps: TaskDeps): Promise<Record<string, unknown>>;
+export {};

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@50heads/mcp",
+  "version": "2026.925.1",
+  "mcpName": "com.50heads/mcp",
+  "description": "50heads MCP: ask fifty verified real people from Claude, ChatGPT, Cursor or your own agent.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "50heads",
+    "human feedback",
+    "agent skill"
+  ],
+  "homepage": "https://50heads.com/docs/mcp",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/50heads/mcp.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": "https://github.com/50heads/mcp/issues",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "50heads-mcp": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types/public.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./skills/*": "./skills/*",
+    "./server.json": "./server.json",
+    "./package.json": "./package.json",
+    "./snippets": {
+      "types": "./dist/types/snippets.d.ts",
+      "default": "./dist/snippets.js"
+    }
+  },
+  "files": [
+    "dist",
+    "skills",
+    "server.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.0.0",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "2.0.0",
+    "@types/node": "^22.18.0",
+    "esbuild": "^0.28.2",
+    "typescript": "^5.9.3",
+    "@50heads/brand": "0.0.0",
+    "@50heads/login": "0.0.0",
+    "@50heads/shared": "0.0.0",
+    "@50heads/tsconfig": "0.0.0"
+  },
+  "scripts": {
+    "generate": "node scripts/generate.ts",
+    "build": "node scripts/build.ts",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --test \"src/**/*.test.ts\" \"scripts/**/*.test.ts\"",
+    "release": "node scripts/release.ts"
+  },
+  "types": "./dist/types/public.d.ts"
+}

package/server.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "com.50heads/mcp",
+  "title": "50heads",
+  "description": "Ask fifty verified real people a five-second question and get the split back.",
+  "version": "2026.925.1",
+  "websiteUrl": "https://50heads.com/agents",
+  "repository": {
+    "url": "https://github.com/50heads/mcp",
+    "source": "github",
+    "subfolder": "packages/mcp"
+  },
+  "icons": [
+    {
+      "src": "https://50heads.com/icon-512.png",
+      "mimeType": "image/png",
+      "sizes": [
+        "512x512"
+      ]
+    },
+    {
+      "src": "https://50heads.com/logo.svg",
+      "mimeType": "image/svg+xml",
+      "sizes": [
+        "any"
+      ]
+    }
+  ],
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://mcp.50heads.com/mcp",
+      "headers": [
+        {
+          "name": "Authorization",
+          "description": "Optional: Bearer fh_live_… for an API key. Without it the host signs in with OAuth.",
+          "isRequired": false,
+          "isSecret": true
+        }
+      ]
+    }
+  ],
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "@50heads/mcp",
+      "version": "2026.925.1",
+      "runtimeHint": "npx",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "FIFTYHEADS_API_KEY",
+          "description": "A 50heads API key (fh_live_…) from the dashboard. Or run `npx @50heads/mcp login` once instead.",
+          "isRequired": false,
+          "isSecret": true,
+          "format": "string"
+        }
+      ]
+    }
+  ],
+  "_meta": {
+    "io.modelcontextprotocol.registry/publisher-provided": {
+      "categories": [
+        "research",
+        "productivity",
+        "human-feedback"
+      ],
+      "authorization": {
+        "resourceMetadata": "https://mcp.50heads.com/.well-known/oauth-protected-resource",
+        "authorizationServer": "https://auth.50heads.com",
+        "scopes": [
+          "questions:read",
+          "questions:write",
+          "templates:read",
+          "account:read"
+        ]
+      },
+      "skillVersion": "2026.925.1"
+    }
+  }
+}

package/skills/50heads/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 50heads
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/50heads/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: 50heads
+description: Ask fifty verified real people a five-second question and get a distribution back; use when the work in hand needs a human preference, first impression or sanity check that a model cannot supply.
+license: MIT
+metadata:
+  version: "2026.925.1"
+  homepage: https://50heads.com/agents
+allowed-tools: "50heads:*"
+---
+
+# Asking 50heads
+
+50heads puts one short question to verified people on their phones and returns how they split. Answers cost credits, priced in your currency; fifty take about ten minutes.
+
+## When to ask
+
+Ask when the answer is a human reaction: which name, headline, image or menu people prefer, whether copy is clear, what they notice first. Never ask for facts, predictions, advice or research. Before asking again, call `list_questions` and reuse a recent answer.
+
+## Eight rules for a good question
+
+1. One question a head can answer in five seconds.
+2. Ask about a preference or first impression, never a fact.
+3. Show the thing: images (`ab_image`, `upload_image`) for anything visual.
+4. Keep options short, parallel and few: two to four is best. Add Neither when a forced pick would mislead.
+5. Word it neutrally. No leading words, no hint of the answer you want.
+6. Put background in `context`, one line, only when a head needs it.
+7. Pick the type that fits: `single_choice` to pick, `pairwise` for two, `ranking` for order, `scale_1_5` for strength, `free_text` (Tier 2) for why.
+8. Match heads and tier to the stakes: 50 at Tier 1 for a quick read, 100 or more or Tier 2 for a decision; target the countries and language of the real audience.
+
+## How to ask
+
+1. Call `estimate` and, when a person is present, show them the price and time together: "50 answers, about 10 minutes, $12.70."
+2. Call `ask` with a fresh UUID as `idempotency_key`. Reuse that key if you retry.
+3. Wait on the task, or call `wait_for_results` on older hosts. `get_results` shows it while live.
+
+## Reading results
+
+Lead with the winner, the margin in points and the confidence. With 50 heads a margin under 10 points is noise: say so and suggest more heads, not a verdict. Report underfilled as underfilled. Quote the split, not adjectives.
+
+## Worked example
+
+"Which menu would you order from?" with two menu photos, `ab_image`, 50 heads, Tier 1. Menu B 68%, Menu A 32%: "Menu B wins by 36 points. Confidence high." Follow up with 20 Tier 2 heads saying why.
+
+## Avoid
+
+- Double questions ("Is it clear and friendly?").
+- Yes-or-no questions that lead.
+- Asking for personal data or anything that identifies someone.
+- Re-asking the same question to fish for a different answer.
+
+More: `references/question-types.md`, `pricing.md`, `tools.md`.

package/skills/50heads/references/pricing.md

@@ -0,0 +1,27 @@
+# Pricing
+
+Prices are in credits. `estimate`, `balance` and 50heads://pricing show them in your account currency at the day's rate. You pay per accepted answer; unanswered heads are refunded.
+
+Per answer = tier base × length × format, plus images and targeting traits, times 1.5 for rush. Total = per answer × heads.
+
+| Tier | Heads | Credits an answer | Credits for 50 answers |
+| --- | --- | --- | --- |
+| 1 | phone-verified | 20 | 1000 |
+| 2 | ID-verified | 42 | 2100 |
+| 3 | trusted panel | 80 | 4000 |
+
+Length (question, context and options together): up to 150 characters × 1.0, up to 300 × 1.1, up to 600 × 1.25.
+
+Format: `single_choice` × 1.0, `multi_choice` × 1.1, `ab_image` × 1.0, `pairwise` × 1.1, `scale_1_5` × 1.0, `ranking` × 1.3, `yes_mostly_no` × 1.0, `free_text` × 2.0, `click_test` × 1.5, `reaction` × 1.0.
+
+A reason with every answer (`reason`, not for free_text) adds to the format: optional + 0.3, required + 0.6. A required reason on a Tier 1 single choice is 20 × 1.6 = 32 credits an answer. Heads get the same share of the higher price.
+
+Images: 7 credits an answer for each image (audio counts the same). Rush: × 1.5. Five-second test: × 1.3.
+
+Targeting: countries are free. Age, gender and each tag group are one trait each, 3 credits an answer per trait, up to 4, at any tier (PickFu charges about $0.40 per trait). See 50heads://targeting.
+
+Heads: 10 to 5000, default 50.
+
+Every connection has a daily spend cap (default 5000 credits), set when you connect and editable in the dashboard. Call `balance` to see what is left.
+
+Always call `estimate` first: it returns the exact price, the time and any fixes the question needs, and never spends.

package/skills/50heads/references/question-types.md

@@ -0,0 +1,235 @@
+# Question types
+
+Every question has `type`, `text` (8 to 600 characters), `language` (such as `en` or `pt-BR`), and optionally `context` (one line, 120 characters), `stimulus` (an image or a line of text shown above the question), `n` (heads, default 50), `tier` (1 to 3, default 1), `rush` and `targeting`.
+
+The format multiplier is part of the price: per answer = tier base × length × format, plus 5 credits an image.
+
+Five-second test: add `exposure_ms` (usually 5000) to an image stimulus on single_choice, multi_choice, yes_mostly_no, scale_1_5, reaction or free_text. The app shows the image for that long, hides it, then asks, so the answer is a first impression or what people remember. × 1.3.
+Every type except `free_text` can ask for a short written reason with each answer: `reason: "optional"` (format + 0.3) or `"required"` (format + 0.6), 10 to 140 characters. Reasons come back on each answer, translated into your language when heads wrote in another, and `get_results` summarises them (themes with counts and quotes, a sentiment split and a takeaway). Use it instead of a follow-up when you want the which and the why from the same heads.
+
+## Single choice (`single_choice`)
+
+- Use: Pick one of several: names, headlines, taglines, colours.
+- Options: 2 to 8 options, 40 characters each; images optional. Two to four reads best.
+- Answer: One option per head; the distribution counts each option.
+- Tier: any. Format × 1.0.
+
+```json
+{
+  "type": "single_choice",
+  "text": "Which name sounds most like a bakery?",
+  "language": "en",
+  "options": [
+    {
+      "label": "Crumb & Co"
+    },
+    {
+      "label": "Loafers"
+    },
+    {
+      "label": "Proof"
+    }
+  ],
+  "n": 50
+}
+```
+
+## Multiple choice (`multi_choice`)
+
+- Use: Tick all that apply: which features matter, which words fit.
+- Options: 2 to 8 options, 40 characters each. Shares add up to more than 100%.
+- Answer: Any number of options per head; each option's share is of all heads.
+- Tier: any. Format × 1.1.
+
+```json
+{
+  "type": "multi_choice",
+  "text": "Which of these would make you try a new coffee shop?",
+  "language": "en",
+  "options": [
+    {
+      "label": "Oat milk at no extra cost"
+    },
+    {
+      "label": "Quiet seating"
+    },
+    {
+      "label": "Loyalty card"
+    }
+  ],
+  "n": 50
+}
+```
+
+## A or B image (`ab_image`)
+
+- Use: Two images side by side: menus, logos, screenshots, packaging.
+- Options: Exactly 2 options, each with an image_url (https, or a pre-signed upload). Labels optional.
+- Answer: One image per head.
+- Tier: any. Format × 1.0.
+
+```json
+{
+  "type": "ab_image",
+  "text": "Which menu would you order from?",
+  "language": "en",
+  "options": [
+    {
+      "label": "Menu A",
+      "image_url": "https://example.com/menu-a.png"
+    },
+    {
+      "label": "Menu B",
+      "image_url": "https://example.com/menu-b.png"
+    }
+  ],
+  "n": 50
+}
+```
+
+## Pairwise (`pairwise`)
+
+- Use: Compare options two at a time when there are too many to show at once.
+- Options: 2 to 8 options; each head sees one pair, balanced so every pair is seen about equally.
+- Answer: One pick per pair. With 3 or more options each row has count (wins), share (win share), appearances, a Bradley–Terry strength and a rank.
+- Tier: any. Format × 1.1.
+
+```json
+{
+  "type": "pairwise",
+  "text": "Which subject line would you open first?",
+  "language": "en",
+  "options": [
+    {
+      "label": "Your order is on its way"
+    },
+    {
+      "label": "Good news: it has shipped"
+    },
+    {
+      "label": "Tracking number inside"
+    }
+  ],
+  "n": 100
+}
+```
+
+## Scale 1 to 5 (`scale_1_5`)
+
+- Use: How strongly: clarity, appeal, trust. Report the mean and the split.
+- Options: Fixed: 1, 2, 3, 4, 5. Do not send options.
+- Answer: A number from 1 to 5; results include the mean.
+- Tier: any. Format × 1.0.
+
+```json
+{
+  "type": "scale_1_5",
+  "text": "How clear is this sentence? 1 is not clear, 5 is very clear.",
+  "context": "Your parcel will be left in a safe place if you are out.",
+  "language": "en",
+  "n": 50
+}
+```
+
+## Ranking (`ranking`)
+
+- Use: Put options in order of preference.
+- Options: 2 to 8 options; keep to five or fewer for a five-second answer.
+- Answer: A full order per head; the distribution carries each option's average rank.
+- Tier: any. Format × 1.3.
+
+```json
+{
+  "type": "ranking",
+  "text": "Rank these pizza toppings, favourite first.",
+  "language": "en",
+  "options": [
+    {
+      "label": "Mushroom"
+    },
+    {
+      "label": "Pepperoni"
+    },
+    {
+      "label": "Olives"
+    },
+    {
+      "label": "Pineapple"
+    }
+  ],
+  "n": 50
+}
+```
+
+## Yes, mostly or no (`yes_mostly_no`)
+
+- Use: A quick check with room for a middle answer: does this make sense, would you trust it.
+- Options: Fixed: Yes, Mostly, No. Do not send options.
+- Answer: One of the three.
+- Tier: any. Format × 1.0.
+
+```json
+{
+  "type": "yes_mostly_no",
+  "text": "Does this button label tell you what will happen?",
+  "context": "Button: Save and continue",
+  "language": "en",
+  "n": 50
+}
+```
+
+## Free text (`free_text`)
+
+- Use: Why, in the head's own words. Best as a follow-up to a choice.
+- Options: No options. Needs Tier 2 or 3. Answers are up to 200 characters.
+- Answer: Short text per head; results carry the texts and a summary.
+- Tier: 2 or 3. Format × 2.0.
+
+```json
+{
+  "type": "free_text",
+  "text": "Why would you order from Menu B?",
+  "language": "en",
+  "n": 20,
+  "tier": 2
+}
+```
+
+## Click test (`click_test`)
+
+- Use: Where people look or tap first on a page, ad, pack or screen. Results are a heatmap.
+- Options: No options. stimulus.image_url is required; max_taps 1 to 5 (default 1).
+- Answer: One to max_taps points per head, 0–1 from the top left. Results carry every tap, the busiest areas with counts and a heatmap PNG.
+- Tier: any. Format × 1.5.
+
+```json
+{
+  "type": "click_test",
+  "text": "Where would you tap to buy this?",
+  "language": "en",
+  "stimulus": {
+    "image_url": "https://example.com/product-page.png"
+  },
+  "max_taps": 1,
+  "n": 50
+}
+```
+
+## Reaction (`reaction`)
+
+- Use: A gut reaction to an image or line: a logo, a cover, an ad. Five faces drawn as glyphs.
+- Options: Fixed: Love it, Like it, Not sure, Dislike it, Hate it. Do not send options.
+- Answer: One of the five; results add a positive, neutral and negative split.
+- Tier: any. Format × 1.0.
+
+```json
+{
+  "type": "reaction",
+  "text": "How does this cover make you feel?",
+  "language": "en",
+  "stimulus": {
+    "image_url": "https://example.com/cover.png"
+  },
+  "n": 50
+}
+```