@50heads/mcp 2026.1009.1 → 2026.1013.2

package/dist/types/server.d.ts

@@ -1,6 +1,6 @@
 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 { MCP_RESOURCE_URL, PROMPT_SCOPES, PUBLIC_RESOURCE_PREFIXES, SERVER_NAME, SERVER_VERSION, TOOL_ACTIONS, TOOL_NAMES, MAX_TOOLS, WRITE_ACTIONS, ACTION_IDS, actionScope, resourceScope, type ActionId, type ToolName, } from "./constants.js";
 export type CallLog = {
     kind: "tool" | "resource" | "prompt";
     name: string;
@@ -22,13 +22,15 @@ export type ServerOptions = {
     authenticated: boolean;
     portalUrl: string;
     webUrl: string;
+    /** The API's public address, for links to it (webhook schemas). Default https://api.50heads.com. */
+    apiUrl?: 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. */
+    /** Longest a single call may block (results, action wait), 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. */
+    /** Fetches public files from webUrl (the help index for help, action search). 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;

package/dist/types/tasks.d.ts

@@ -31,8 +31,8 @@ export type TaskObject = {
     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;
+/** "12 of 50 answered" */
+export declare function statusMessage(q: Pick<QuestionV2, "status" | "answered" | "n" | "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. */

package/dist/types/tool-schema.d.ts

@@ -0,0 +1,64 @@
+import { z } from "zod";
+/**
+ * How one tool that takes an `action` is described to a host and validated for the server.
+ *
+ * Every action has its own input object. The server validates a call with a discriminated union
+ * on `action`, so each action's arguments are checked against that action's schema alone. Hosts
+ * need a plain object at the root of a tool's input schema (several refuse oneOf or anyOf there),
+ * so tools/list carries one merged object instead: `action` (an enum, required) and every
+ * argument of every action, each saying which actions use it. The description lists each action
+ * with its arguments, so a model can choose well without reading the schema.
+ */
+export type ActionSpec = {
+    /** The action's name, such as "get". */
+    name: string;
+    /** What the action does, in plain words (its part of the tool's description). */
+    description: string;
+    /** The action's own arguments, without `action`. */
+    input: z.ZodObject;
+    /** The scope the action needs; null when it needs no sign-in. */
+    scope: string | null;
+    /** True when the action changes nothing. */
+    readOnly: boolean;
+    destructive: boolean;
+    idempotent: boolean;
+};
+type Json = Record<string, unknown>;
+/** The one plain-object JSON Schema tools/list carries for a tool. */
+export declare function mergedInputSchema(tool: string, actions: ActionSpec[]): Json;
+/** A Standard Schema (with JSON Schema) that validates with the union and shows hosts the merged object. */
+export type PublishedInput = {
+    "~standard": {
+        version: 1;
+        vendor: string;
+        validate: (value: unknown) => unknown;
+        jsonSchema: {
+            input: () => Json;
+            output: () => Json;
+        };
+    };
+};
+export declare function publishedInput(union: z.ZodType, merged: Json): PublishedInput;
+/** The discriminated union a call is validated with. */
+export declare function inputUnion(actions: ActionSpec[]): z.ZodDiscriminatedUnion<[z.ZodObject<{
+    [x: string]: any;
+    action: z.ZodLiteral<string>;
+}, z.core.$strip>, ...z.ZodObject<{
+    [x: string]: any;
+    action: z.ZodLiteral<string>;
+}, z.core.$strip>[]], "action">;
+/** The tool's description: its purpose, then every action with its arguments and what it needs. */
+export declare function toolDescription(intro: string, actions: ActionSpec[]): string;
+/** The tool-level hints, true to every action in it. */
+export declare function toolAnnotations(actions: ActionSpec[]): {
+    readOnlyHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+    destructiveHint?: undefined;
+} | {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+};
+export {};

package/dist/types/webhooks.d.ts

@@ -0,0 +1,35 @@
+import { WEBHOOK_EVENTS, type WebhookEndpoint, type WebhookFilter } from "@50heads/shared";
+import type { WebhookDelivery as DeliverySchema } from "@50heads/shared";
+import type { z } from "zod";
+import type { WebhookDeliveryOut, WebhookEndpointOut, WebhookFilterInput } from "./schemas.js";
+/** What each event type means, for 50heads://webhook-events and the tool descriptions. */
+export declare const WEBHOOK_EVENT_NOTES: Record<(typeof WEBHOOK_EVENTS)[number] | "webhook.test", string>;
+/** The API's endpoint as the tools return it (snake_case). */
+export declare function toEndpoint(e: WebhookEndpoint): WebhookEndpointOut;
+export declare function toDelivery(d: z.infer<typeof DeliverySchema>): WebhookDeliveryOut;
+/** snake_case filter → the API's; null stays null (clears), undefined stays undefined. */
+export declare function fromFilter(f: z.infer<typeof WebhookFilterInput> | null | undefined): WebhookFilter | null | undefined;
+/** One line per endpoint for the text content. */
+export declare function endpointLine(e: WebhookEndpointOut): string;
+export declare function deliveryLine(d: WebhookDeliveryOut): string;
+/** The 50heads://webhook-events resource: event types, what they carry and where the schemas are. */
+export declare function webhookEventsDoc(apiUrl: string, webUrl: string): {
+    apiVersions: "2026-10-10"[];
+    latest: "2026-10-10";
+    schemas: string;
+    docs: string;
+    events: {
+        type: "question.reserved" | "question.completed" | "question.underfilled" | "question.canceled" | "question.refused" | "credits.purchased" | "credits.low" | "credits.expiring" | "dispute.resolved" | "connection.cap_warning" | "webhook.test" | "member.provisioned" | "member.deprovisioned" | "policy.changed" | "approval.requested" | "approval.decided" | "approval.expired" | "approval.refused";
+        description: string;
+        schema: string;
+    }[];
+    envelope: string;
+    filters: string;
+    signing: {
+        standard: string;
+        legacy: string;
+        rotation: string;
+        tolerance: string;
+    };
+    retries: string;
+};

package/dist/types/workspace-apps.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Workspace apps (the Slack and Microsoft Teams apps) and Zapier connections as the tools return them: snake_case,
+ * credits, and a person's name or email for who added it. Read-only here; installs are added and
+ * removed in the portal, and Zapier connects from Zapier.
+ */
+import type { WorkspaceApp, ZapierConnection } from "@50heads/shared";
+import type { WorkspaceAppOut, ZapierConnectionOut } from "./schemas.js";
+export declare function toWorkspaceApp(a: WorkspaceApp): WorkspaceAppOut;
+/** One line per install: "app_1 · Slack · Acme: 400 of 2,000 credits spent today. Added by Ana on 2026-10-10." */
+export declare function workspaceAppLine(a: WorkspaceAppOut): string;
+export declare function toZapierConnection(z: ZapierConnection): ZapierConnectionOut;
+/** "conn_1 · Zapier: 2 hooks; 1,200 of 5,000 credits spent today. Connected by Ana on 2026-10-09." */
+export declare function zapierLine(z: ZapierConnectionOut): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@50heads/mcp",
-  "version": "2026.1009.1",
+  "version": "2026.1013.2",
   "mcpName": "com.50heads/mcp",
   "description": "50heads MCP: ask fifty verified people from Claude, ChatGPT, Cursor or your own agent.",
   "keywords": [
@@ -57,8 +57,8 @@
     "@types/node": "^22.18.0",
     "esbuild": "^0.28.2",
     "typescript": "^5.9.3",
-    "@50heads/login": "0.0.0",
     "@50heads/brand": "0.0.0",
+    "@50heads/login": "0.0.0",
     "@50heads/shared": "0.0.0",
     "@50heads/tsconfig": "0.0.0"
   },
@@ -67,7 +67,8 @@
     "build": "node scripts/build.ts",
     "typecheck": "tsc -p tsconfig.json",
     "test": "node --test \"src/**/*.test.ts\" \"scripts/**/*.test.ts\"",
-    "release": "node scripts/release.ts"
+    "release": "node scripts/release.ts",
+    "smoke": "node scripts/smoke.ts"
   },
   "types": "./dist/types/public.d.ts"
 }

package/server.json

@@ -2,8 +2,8 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "com.50heads/mcp",
   "title": "50heads",
-  "description": "Ask fifty verified people a five-second question and get the split back.",
-  "version": "2026.1009.1",
+  "description": "Ask fifty verified people a five-second question and see what they think.",
+  "version": "2026.1013.2",
   "websiteUrl": "https://50heads.com/agents",
   "repository": {
     "url": "https://github.com/50heads/mcp",
@@ -44,7 +44,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@50heads/mcp",
-      "version": "2026.1009.1",
+      "version": "2026.1013.2",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"
@@ -67,6 +67,11 @@
         "productivity",
         "human-feedback"
       ],
+      "documentationUrl": "https://50heads.com/en-us/docs/mcp",
+      "privacyPolicyUrl": "https://50heads.com/en-gb/legal/privacy",
+      "noTrainStatementUrl": "https://50heads.com/en-gb/help/privacy/ai-and-your-data",
+      "termsOfServiceUrl": "https://50heads.com/en-gb/legal/terms",
+      "supportUrl": "https://50heads.com/en-gb/contact?purpose=support",
       "authorization": {
         "resourceMetadata": "https://mcp.50heads.com/.well-known/oauth-protected-resource",
         "authorizationServer": "https://auth.50heads.com",
@@ -74,10 +79,19 @@
           "questions:read",
           "questions:write",
           "templates:read",
-          "account:read"
+          "account:read",
+          "webhooks:read",
+          "webhooks:write",
+          "apps:read",
+          "apps:write",
+          "organization:read",
+          "organization:write",
+          "members:read",
+          "members:write",
+          "audit:read"
         ]
       },
-      "skillVersion": "2026.1009.1"
+      "skillVersion": "2026.1013.2"
     }
   }
 }

package/skills/50heads/SKILL.md

@@ -3,18 +3,18 @@ name: 50heads
 description: Ask fifty verified 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.1009.1"
+  version: "2026.1013.2"
   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.
+50heads puts one short question to verified people and shows what they think.
 
 ## 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.
+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. Check recent `results` (`list`) first.
 
 ## Eight rules for a good question
 
@@ -22,30 +22,35 @@ Ask when the answer is a human reaction: which name, headline, image or menu peo
 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.
+5. Word it neutrally, with no hint of the answer you want.
+6. Put needed background in `context`, one line.
+7. Pick the type that fits: `single_choice` to pick, `pairwise` for two, `ranking` for order, `scale_1_5` for strength, `yes_no` with `go_rule` to approve, `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 real audience's countries and language.
 
 ## 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.
+1. Call `estimate` (`quote`); with a person present, show the price: "50 answers, $12.70." Don't promise a time.
+2. Call `ask` with a fresh UUID as `idempotency_key`. Reuse it to retry.
+3. Wait on the task (older hosts: `results`, `wait`).
 
 ## 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.
+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. Report underfilled as underfilled. Quote the percentages, not adjectives.
+
+With a `go_rule`, lead with the `verdict`: go, no go or unclear against the asker's line. `head_to_head` says who beats whom; overlapping ranges mean the lead may be chance.
 
 ## 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.
+"Which menu would you order from?": two photos, `ab_image`, 50 heads, Tier 1. B 68%, A 32%: "Menu B wins by 36 points. Confidence high."
 
 ## 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.
+- Personal data, or anything that identifies someone.
+- Re-asking to fish for a different answer.
+
+## Your data
+
+We don't use your questions, the answers you buy or the reasons heads write to train AI models, and we don't sell them.
 
 More: `references/question-types.md`, `pricing.md`, `tools.md`.

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

@@ -1,6 +1,6 @@
 # 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.
+Prices are in credits. `estimate` (quote and 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.
 
@@ -26,4 +26,4 @@ Your audience (`answered_by: "private"`): a link you share instead of heads, 5 c
 
 Every connection has a daily spend cap (default 5,000 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.
+Always call `estimate` (action quote) first: it returns the exact price, the time and any fixes the question needs, and never spends.

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

@@ -5,11 +5,11 @@ Every question has `type`, `text` (8 to 600 characters), `language` (such as `en
 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_no, 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.
+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 `results` (action get) summarizes 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.
+- Use: Pick one of several: names, headlines, taglines, colors.
 - 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.
@@ -91,7 +91,7 @@ Every type except `free_text` can ask for a short written reason with each answe
 
 - 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.
+- Answer: One pick per pair. With 3 or more options each row has count (wins), share (win share), a 95% range on it (low, high), appearances, a Bradley–Terry strength and a rank. When the top two ranges overlap, the lead may be chance. head_to_head says who beats whom: share[i][j] is the share of people who put option i above option j.
 - Tier: any. Format × 1.1.
 
 ```json
@@ -135,13 +135,13 @@ Every type except `free_text` can ask for a short written reason with each answe
 
 - 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.
+- Answer: A full order per head; the distribution carries each option's average rank, and head_to_head says who beats whom: share[i][j] is the share of people who put option i above option j.
 - Tier: any. Format × 1.3.
 
 ```json
 {
   "type": "ranking",
-  "text": "Rank these pizza toppings, favourite first.",
+  "text": "Rank these pizza toppings, favorite first.",
   "language": "en",
   "options": [
     {
@@ -163,9 +163,9 @@ Every type except `free_text` can ask for a short written reason with each answe
 
 ## Yes or no (`yes_no`)
 
-- Use: A binary check. Heads answer Yes or No. This is the yes/no type. For a middle answer, use yes_mostly_no.
+- Use: A binary check. Heads answer Yes or No. This is the yes/no type. For a middle answer, use yes_mostly_no. For an approval-style question, add go_rule to get a go or a no go when Yes clears your line.
 - Options: Fixed: Yes, No. Do not send options.
-- Answer: Yes or No.
+- Answer: Yes or No. With go_rule ({ "go_above": 0.6, "min_answers": 40 }), results carry a verdict: go when the whole 95% range on the Yes share is above the line, no_go when it is all at or below it, otherwise unclear (too few answers, or the range crosses the line). The line is fixed once the question is live and costs nothing extra.
 - Tier: any. Format × 1.0.
 
 ```json
@@ -174,15 +174,19 @@ Every type except `free_text` can ask for a short written reason with each answe
   "text": "Does this button label tell you what will happen?",
   "context": "Button: Save and continue",
   "language": "en",
-  "n": 50
+  "n": 50,
+  "go_rule": {
+    "go_above": 0.6,
+    "min_answers": 40
+  }
 }
 ```
 
 ## Yes, mostly or no (`yes_mostly_no`)
 
-- Use: Yes, Mostly or No. Set this type when you want the middle answer. A plain yes/no question is yes_no.
+- Use: Yes, Mostly or No. Set this type when you want the middle answer. A plain yes/no question is yes_no. Takes go_rule like yes_no.
 - Options: Fixed: Yes, Mostly, No. Do not send options.
-- Answer: One of the three.
+- Answer: One of the three. With go_rule, Mostly counts as half a Yes in the verdict.
 - Tier: any. Format × 1.0.
 
 ```json

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

@@ -1,27 +1,88 @@
 # 50heads tools beyond asking
 
-The core loop is `estimate`, `ask`, then the task (or `wait_for_results`) and `get_results`. These tools cover the rest.
+50heads has nine tools, and every tool takes an `action` plus that action's own arguments: `estimate`, `ask`, `results`, `questions`, `projects`, `webhooks`, `organization`, `audit` and `help`. Below, "`results` action `get`" means the tool `results` called with `action: "get"`. Each action is checked against its own scope, so a connection can read without being able to change anything.
+
+The core loop is `estimate` action `quote`, `ask` action `ask`, then the task (or `results` action `wait`) and `results` action `get`. These actions cover the rest.
 
 ## Before asking
 
-- `upload_image`: for a local file or a generated image, send it as base64 in `data` (JPEG, PNG or WebP, up to 5 MB; about 700 KB through the hosted server, which takes 1 MB requests). For an image already online, pass `image_url` and 50heads copies it. Use the returned `image_url` in the question. Costs nothing.
-- `list_audiences`: interest audiences, panels of heads who proved they fit (UK commuter cyclists, for example). Put an id in `question.audience` to ask one instead of targeting; the price is the audience's at the minimum grade.
-- `list_targeting`: countries with the languages their heads read and pool size bands, and the tag ids you can target at Tier 2 and 3. Each condition shrinks the pool; `estimate` shows `pool_size`.
-- `build_ask_link`: when a person should press Ask themselves, give them this link. It opens the portal composer with the question filled in and asks nothing. It also opens a template (`template_id`), a follow-up (`follow_up_of`) or a re-ask of the unanswered part (`reask`).
-- `templates` and `list_questions`: a fixed-price template may fit, and a recent answer may already cover the question. `list_questions` takes `set_id` to list one set's questions in order.
-- `ask_set`: two to ten questions for the person's own audience behind one link, answered in order, about five seconds each. Same question shapes as `ask` without tier, rush, targeting, reasons or free text; `max_answers`, `open_for_days`, `shown_as` and `public_results` are set once for the set. Returns the link, the `question_ids` in order and the reserve (questions × max answers × 5 credits). Results are per question.
+- `estimate` action `quote`: price, time and any fixes for a question; never spends. `estimate` action `balance`: your credits, what live questions have reserved and what is left under the connection's daily cap; check it before asking something large.
+- `ask` action `upload_image`: for a local file or a generated image, send it as base64 in `data` (JPEG, PNG or WebP, up to 5 MB; about 700 KB through the hosted server, which takes 1 MB requests). For an image already online, pass `image_url` and 50heads copies it. Use the returned `image_url` in the question. Costs nothing.
+- `estimate` action `audiences`: interest audiences, panels of heads who proved they fit (UK commuter cyclists, for example). Put an id in `question.audience` to ask one instead of targeting; the price is the audience's at the minimum grade.
+- `estimate` action `targeting`: countries with the languages their heads read and pool size bands, and the tag ids you can target at Tier 2 and 3. Each condition shrinks the pool; `estimate` action `quote` shows `pool_size`.
+- `ask` action `build_link`: when a person should press Ask themselves, give them this link. It opens the portal composer with the question filled in and asks nothing. It also opens a template (`template_id`), a follow-up (`follow_up_of`) or a re-ask of the unanswered part (`reask`).
+- `estimate` action `templates` and `results` action `list`: a fixed-price template may fit, and a recent answer may already cover the question. `results` action `list` takes `set_id` to list one set's questions in order.
+- `ask` action `set`: two to ten questions for the person's own audience behind one link, answered in order, about five seconds each. Same question shapes as `ask` action `ask` without tier, rush, targeting, reasons or free text; `max_answers`, `open_for_days`, `shown_as` and `public_results` are set once for the set. Returns the link, the `question_ids` in order and the reserve (questions × max answers × 5 credits). Results are per question.
+
+## Go or no go, and who beats whom
+
+- `go_rule` on a `yes_no` or `yes_mostly_no` question: `{ "go_above": 0.6, "min_answers": 40 }` means go when Yes is above 60%, with at least 40 answers. `go_above` is a whole percentage from 0.5 to 0.95; `min_answers` is at least 5 and at most `n`, and defaults to 80% of `n`. On `yes_mostly_no`, Mostly counts as half a Yes. Use it for approval-style questions, where you will act on the answer: "Is this label clear enough to ship?" Set it before asking: the line cannot move once the question is live, and it costs nothing extra. Other types refuse it.
+- `verdict` in the results: `go` when the whole 95% range on the Yes share (`low` to `high`) is above `go_above`, `no_go` when it is all at or below it, otherwise `unclear`, with `reason` `too_few` (fewer than `min_answers`) or `too_close` (the range crosses the line; `questions` action `add_heads` can settle it). The summary note opens with the same sentence. Report it as how these heads answered against the line, not as a fact.
+- `head_to_head` for `ranking`, and `pairwise` with 3 or more options: `share[i][j]` is the share of people who compared options i and j and put i above j, and `n[i][j]` how many compared them. Use it to say who beats whom, not just who came first.
+- Pairwise rows also carry `low` and `high`, a 95% range on each win share. When the top two ranges overlap, the top two are close and the lead may be chance.
 
 ## After the answers
 
-- `get_answers`: individual answers, 50 a page (up to 200), newest first, with `next_cursor`. Filter by `option` (0 is the first), `tier`, `country`, `age_band` or a keyword `q` in written answers and reasons. Country and age filters show nothing when fewer than 5 answers match, so no head can be singled out.
-- `add_heads`: when the margin is under 10 points with 50 heads, ask more of the same question instead of a new one. It needs its own fresh `idempotency_key` and spends at the same price per answer; say the price and time before you do it when a person is present.
-- `flag_answer`: an answer that is off-topic, low effort, offensive or a duplicate, by its `attestation_ref`. Upheld flags remove the answer and refund it. Never flag an answer because you dislike it.
-- `export`: `csv` has every answer (with the same filters as `get_answers`); `pdf` is a one-page report and `png` the result card. The API serves all three.
-- `cancel`: stops a live question and refunds the heads who have not answered.
+- `results` action `answers`: individual answers, 50 a page (up to 200), newest first, with `next_cursor`. Filter by `option` (0 is the first), `tier`, `country`, `age_band` or a keyword `q` in written answers and reasons. Country and age filters show nothing when fewer than 5 answers match, so no head can be singled out.
+- `questions` action `add_heads`: when the margin is under 10 points with 50 heads, ask more of the same question instead of a new one. It needs its own fresh `idempotency_key` and spends at the same price per answer; say the price and time before you do it when a person is present.
+- `questions` action `flag_answer`: an answer that is off-topic, low effort, offensive or a duplicate, by its `attestation_ref`. Upheld flags remove the answer and refund it. Never flag an answer because you dislike it.
+- `results` action `export`: `csv` has every answer (with the same filters as `results` action `answers`); `jsonl` has the same answers as JSON lines, one object per answer with `choice` (option indexes) and `cohortHash`, for scripts and model training; `pdf` is a one-page report and `png` the result card. The API serves all four.
+- `choice` on each answer (in `results` action `get`, `results` action `answers` and the JSONL export) is the answer as indexes into the options: `index` (one pick, or a rating's 1 to 5 as 0 to 4), `indexes` (pick several), `order` (ranking, best first) or `pair` (the two options shown in a pairwise matchup of 3 or more options). Absent for free text and click tests.
+- `cohort_hash` in `results` action `get` (`cohortHash` in the JSONL export): the same value means the same kind of audience was asked (who answers, how many, which tier and targeting, language and type). It never covers the words asked and never identifies anyone. Use it to group results from different questions put to the same audience.
+- `questions` action `cancel`: stops a live question and refunds the heads who have not answered.
+
+## Filing questions
+
+- `projects` action `list`, `projects` action `create`, `projects` action `update`, `projects` action `delete`: projects group questions under a name and a description. `projects` action `list` shows each with its question count; archived projects only with `include_archived`. `projects` action `update` renames, redescribes or archives one; archiving leaves its questions as they are. `projects` action `delete` removes the project for good but never its questions: they keep their answers and results and are left outside any project. Confirm with the person before deleting.
+- `questions` action `file`: moves one question into a project (`project_id`, or `null` to take it out), replaces its `labels` (up to 10, no commas), archives or bookmarks it, or sets your `external_ref`. Send only what should change. `external_ref` is set once: the same value again is fine, a different one is refused. Cancel a live question before archiving it.
+- `projects` action `labels`: the labels in use, most used first, with counts.
+- `ask` actions `ask` and `set` take `project_id` and `labels` to file as they ask; `results` action `list` filters by `project_id`, `label`, `external_ref`, `bookmarked` and `archived`.
+
+With a team key, projects and labels are the team's.
+
+## Webhooks
+
+Webhooks send events (a question completed, underfilled or refused, credits low, and more) to an https address as they happen, so a script or a CI job does not have to poll. They need the `webhooks:read` and `webhooks:write` scopes, which a connection gets only when the person grants them. Read `50heads://webhook-events` for every event type, what it carries and the links to its JSON Schema.
+
+- `webhooks` action `create`: `url`, `events`, an optional `description`, and a `filter` of `project_ids` or `labels` to send question events only for those. It sends this account's question events to that address, so only use an address the person owns and asked for, and confirm it with them first. The signing secret is in the reply once: give it to the person to store with the receiver. Then `webhooks` action `test`.
+- `webhooks` action `list`: each endpoint with its events, filter, whether it is on and the last delivery's status. Secrets are masked.
+- `webhooks` action `update`: change `url`, `events`, `description` or `filter` (`null` clears it). `enabled: false` pauses; `enabled: true` turns it back on, also after 50heads switched it off for failing.
+- `webhooks` action `rotate_secret`: a new secret, returned once. The old one keeps signing for `overlap_hours` (default 24, up to 168), so the receiver can switch without missing a delivery; `0` cuts over at once.
+- `webhooks` action `test`: sends a signed `webhook.test` event now and says how the receiver answered.
+- `webhooks` action `deliveries`: the latest 100, filtered by `endpoint_id` or `state`. `failed` means out of retries (8 attempts over about a day).
+- `webhooks` action `events`: the latest events of one `type` in this account, newest first (`limit` 1 to 25, default 3), each exactly as a delivery's body carries it. Events are kept whether or not an endpoint listens: use one as a sample payload when writing a receiver.
+- `webhooks` action `replay`: sends a delivery's event again, with the same event id, so receivers that drop duplicates stay safe.
+- `webhooks` action `delete`: removes the endpoint for good; pausing is usually better. Confirm with the person first.
+
+Each delivery is signed twice: Standard Webhooks headers (`webhook-id`, `webhook-timestamp`, `webhook-signature`) and `X-50heads-Signature`. Verify either one, refuse timestamps more than 5 minutes old, and drop event ids you have already handled. `50heads webhooks verify` checks a captured delivery offline.
+
+## Slack and Zapier
+
+- `organization` action `apps`: the Slack workspaces 50heads is added to, each with its daily spend cap and what it has spent today, in credits, and who added it. People in those workspaces ask with `/50heads ask`, spending this account's credits within that cap. It also lists the Zapier accounts connected to this one (`zapier`), each with its daily cap, today's spend and live hooks, one per Zap trigger. It needs the `apps:read` scope. Adding, changing the cap and removing happen in the portal (Settings, Integrations), not from here; removing a Zapier connection deletes its hooks.
+
+## Organization (admins)
+
+These read an organization and never change it. They work with an organization admin's key or connected app that holds the scope, or with one of the organization's own service accounts; anyone else gets `insufficient_scope` or `organization_admin_required`. Changes to domains, sign-in rules, single sign-on, SCIM and service accounts are made by a person in the portal (Settings, Organization).
+
+- `organization` action `get` (`organization:read`): the organization of the workspace you act in: workspaces, verified domains, whether single sign-on is set up or required, whether SCIM is connected, its sign-in rules.
+- `organization` action `domains` (`organization:read`): each domain's state and the DNS TXT record that proves it, to pass to whoever manages DNS.
+- `audit` action `list` (`audit:read`): who did what, newest first. Filter with `from`, `to`, `actor` (a user id or a service account id, `sa_…`), `event_action` (an audit action such as `domain.added`, or a group such as `sso`) and `workspace_id`; page with `next_cursor`. Each event says whether a person, a key, a connected app, a service account, SCIM or 50heads acted.
+- `audit` action `export` (`audit:read`): the same events as JSON lines, oldest first, up to `max_events` at a time with a `resume_cursor`. Every export is itself recorded in the log.
+- `organization` action `scim` (`organization:read`): SCIM provisioning: how many people and groups the identity provider has sent, the default role, and its tokens by label and prefix.
+- `organization` action `member_sessions` (`members:read`): where one person is signed in, and how each session started.
+- `organization` action `service_accounts` (`organization:read`): the organization's service accounts, with their workspace, scopes, caps in credits, today's spend and last token. Never their secrets.
+
+Events and lists never hold secrets, one-time codes or anything that identifies a head.
 
 ## Help
 
-- `search_help`: the help centre, for questions about credits, refunds, verification, tiers, the API or this server.
-- `send_feedback`: tells support about a problem or an idea. Signed out, add `email`. Leave out personal data about other people.
+- `help` action `search`: the help center, for questions about credits, refunds, verification, tiers, the API or this server.
+- `help` action `feedback`: tells support about a problem or an idea. Signed out, add `email`. Leave out personal data about other people.
+- `help` action `whoami`: who the connection acts as (email masked), its scopes, daily and per-question caps and today's spend, the account and organization, and the rate limits with what is used. Call it first when something is refused.
+- `help` action `status`: whether 50heads is working and whether asking, answering, MCP asking or buying credits is paused. Needs no sign-in. Check it when calls fail, and do not ask while asking is paused.
+
+`questions` actions `add_heads` and `flag_answer`, and `results` action `export` (CSV, JSONL, PDF and PNG), are served by the API. Use them when the result calls for it.
+
+## Your data
 
-`add_heads`, `flag_answer` and `export` (CSV, PDF and PNG) are served by the API. Use them when the result calls for it.
+We don't use your questions, the answers you buy or the reasons heads write to train AI models, and we don't sell them.

package/skills/50heads/scripts/estimate.py

@@ -107,7 +107,7 @@ def main():
     cost = "%d credits" % quote["creditsTotal"]
     if quote.get("price"):
         cost += " (%s)" % money(quote["price"])
-    print("%d answers, about %d minutes, %s." % (n, quote["etaMinutes"], cost))
+    print("%d answers, %s." % (n, cost))
     print(quote.get("breakdownLine", ""))
     for issue in quote.get("validation", []):
         print("Fix: " + issue["message"])