Recipes

Concrete patterns you can copy and adapt. Each one assumes userintuition-mcp is on your PATH and you have either run userintuition-mcp login or set USERINTUITION_API_KEY.

Cost gate in CI

Refuse to merge a PR if its planned panel recruit would exceed a budget. estimate_panel returns the current cost and heuristic timeline without launching or charging anything:

#!/usr/bin/env bash
set -euo pipefail

estimate=$(userintuition-mcp estimate_panel \
  --study_id "$STUDY_ID" \
  --target 25 \
  --incident_rate 50 \
  --country_code US)

cost_usd=$(jq -r '.estimated_total_cost_usd' <<<"$estimate")

budget_usd=750

if (( $(echo "$cost_usd > $budget_usd" | bc -l) )); then
  echo "::error::Panel would cost \$$cost_usd — exceeds \$$budget_usd cap" >&2
  exit 1
fi

echo "Panel estimate: \$$cost_usd ✓"

Panel lifecycle script

Field a panel for an existing Panel study, poll until the target number of interviews lands (or 24 hours elapse), then generate and export the report:

#!/usr/bin/env bash
set -euo pipefail

study_id="$1"
target=25

# 1. Launch (dry-run first if you haven't previewed the cost — see the CI gate above)
userintuition-mcp launch_panel \
  --study_id "$study_id" \
  --target "$target" \
  --incident_rate 50 \
  --country_code US \
  --dry_run false
echo "Panel launched for $study_id"

# 2. Poll — list_interviews returns a total_count envelope, so page_size 1 is
#    enough. Filter to completed interviews: the unfiltered total also counts
#    in-progress and failed sessions.
deadline=$(( $(date +%s) + 86400 ))
while (( $(date +%s) < deadline )); do
  n=$(userintuition-mcp list_interviews \
      --study_id "$study_id" --status completed --page_size 1 \
      | jq -r '.total_count // 0')
  echo "  completed=$n/$target"
  (( n >= target )) && break
  sleep 600
done

# 3. Analyze and export
userintuition-mcp generate_report --study_id "$study_id" > /dev/null
userintuition-mcp get_study_report --study_id "$study_id" \
  > "report-$study_id.json"
echo "Saved: report-$study_id.json"

Daily standup digest

A cron job that writes per-study interview counts into a Slack-ready text file every morning. list_interviews with page_size: 1 is the cheap way to count — the envelope’s total_count covers the whole study, not just the page:

#!/usr/bin/env bash
set -euo pipefail

userintuition-mcp list_studies --page_size 50 \
  | jq -r '.studies[] | "\(.id)\t\(.name)"' \
  | while IFS=$'\t' read -r id name; do
      n=$(userintuition-mcp list_interviews \
          --study_id "$id" --status completed --page_size 1 \
          | jq -r '.total_count // 0')
      echo "  • $name — $n completed interviews"
    done > /tmp/studies-digest.txt

# Then post via your Slack tool of choice
cat /tmp/studies-digest.txt

Schedule with cron:

0 9 * * 1-5 USERINTUITION_API_KEY=ui_sk_... /usr/local/bin/digest.sh

Bulk cleanup of test studies

Delete every study whose name starts with test_:

userintuition-mcp list_studies --page_size 100 \
  | jq -r '.studies[] | select(.name | startswith("test_")) | .id' \
  | while read -r id; do
      echo "Deleting $id"
      userintuition-mcp delete_study --study_id "$id"
    done

delete_study is destructive. Sanity-check the jq filter against list_studies output before running the loop.

Review low-quality interviews

List interviews classified as Poor, then fetch each full record for review:

#!/usr/bin/env bash
set -euo pipefail

study_id="$1"

userintuition-mcp list_interviews \
  --study_id "$study_id" --quality '["Poor"]' --page_size 100 \
  | jq -r '.interviews[].id' \
  | while read -r id; do
      userintuition-mcp get_interview --interview_id "$id" > "interview-$id.json"
      echo "Saved interview-$id.json"
    done

delete_interview --interview_id <id> is available after review, but deletion is destructive. The public API does not expose a reversible hide operation.

Discovering tools by capability

The CLI ships every tool the MCP server has. To find one for a job:

# Anything that creates something
userintuition-mcp list | grep ^create_

# Anything related to interviews
userintuition-mcp list | grep interview

# Inspect a candidate
userintuition-mcp describe create_participants

This is often faster than scrolling the tool reference.

Patterns to avoid

Don’t hard-code IDs. Always derive them from a fresh list_* call. IDs from a teammate’s account won’t resolve.
Don’t omit --dry_run true when iterating on a panel launch. Real recruiting starts the moment you flip it to false.
Don’t count by page. Read list_interviews.total_count instead of counting one page’s interviews array.
Don’t parse stdout in shell with grep/sed. Use jq — responses are JSON and may add fields between versions.
Don’t share your USERINTUITION_API_KEY in CI logs. Mask it as a secret. Anyone with the key can spend panel budget on your account.

Get Started

Reference

Guides

Cost gate in CI

Panel lifecycle script

Daily standup digest

Bulk cleanup of test studies

Review low-quality interviews

Discovering tools by capability

Patterns to avoid

​Cost gate in CI

​Panel lifecycle script

​Daily standup digest

​Bulk cleanup of test studies

​Review low-quality interviews

​Discovering tools by capability

​Patterns to avoid

Cost gate in CI

Panel lifecycle script

Daily standup digest

Bulk cleanup of test studies

Review low-quality interviews

Discovering tools by capability

Patterns to avoid