{
 "key": "headcountlabs-mcp-answer-key",
 "version": 2,
 "written": "2026-10-08",
 "about": "What a customer says to an AI agent connected to the Headcount Labs MCP, and the tool call(s) the agent should make. Each case is run against the live MCP by run-key.py. {{today-N}} is a date N days ago; {{prev.X}} is a value from the previous call's result.",
 "cases": [
  {
   "id": "count-all",
   "say": "How many jobs do you have?",
   "calls": [
    {
     "tool": "count_jobs",
     "args": {}
    }
   ],
   "expect": "count",
   "rule": "No filters counts every published job."
  },
  {
   "id": "count-title-state",
   "say": "How many nursing jobs are there in California?",
   "calls": [
    {
     "tool": "count_jobs",
     "args": {
      "filters": {
       "title": "nurse",
       "state": "CA"
      }
     }
    }
   ],
   "expect": "count",
   "rule": "state alone means a U.S. state, as a two-letter code."
  },
  {
   "id": "count-company-open",
   "say": "How many open jobs does Salesforce have?",
   "calls": [
    {
     "tool": "count_jobs",
     "args": {
      "filters": {
       "company": "salesforce",
       "active": true
      }
     }
    }
   ],
   "expect": "count",
   "rule": "company matches the employer name as text; active=true keeps jobs whose currentness is current."
  },
  {
   "id": "search-remote",
   "say": "Find remote software engineer jobs.",
   "calls": [
    {
     "tool": "search_jobs",
     "args": {
      "filters": {
       "title_advanced": "\"software engineer\" OR \"software developer\"",
       "work_arrangement": "remote"
      },
      "limit": 10
     }
    }
   ],
   "expect": "jobs",
   "rule": "Remote is work_arrangement=remote, not a word search. title_advanced catches the common title variants."
  },
  {
   "id": "search-senior",
   "say": "Show me senior software engineer jobs.",
   "calls": [
    {
     "tool": "search_jobs",
     "args": {
      "filters": {
       "title_advanced": "senior AND (\"software engineer\" OR \"software developer\")"
      },
      "limit": 10
     }
    }
   ],
   "expect": "jobs",
   "rule": "title matches the words as one phrase in order, so title=\"senior software engineer\" misses \"Software Engineer, Senior\". Use title_advanced."
  },
  {
   "id": "search-company",
   "say": "What jobs is Salesforce hiring for?",
   "calls": [
    {
     "tool": "search_jobs",
     "args": {
      "filters": {
       "company": "salesforce",
       "active": true
      },
      "limit": 10
     }
    }
   ],
   "expect": "jobs",
   "rule": "company is a case-insensitive contains match on the employer name."
  },
  {
   "id": "search-recent-state",
   "say": "Jobs posted in Texas in the last week.",
   "calls": [
    {
     "tool": "search_jobs",
     "args": {
      "filters": {
       "state": "TX",
       "posted_since": "{{today-7}}"
      },
      "limit": 10
     }
    }
   ],
   "expect": "jobs",
   "rule": "posted_since is the date the source published the job; a plain date works."
  },
  {
   "id": "search-pay-min",
   "say": "Data analyst jobs paying at least $100k a year.",
   "calls": [
    {
     "tool": "search_jobs",
     "args": {
      "filters": {
       "title": "data analyst",
       "pay_min": 100000
      },
      "limit": 10
     }
    }
   ],
   "expect": "jobs",
   "rule": "pay_min is yearly; hourly pay is converted at 2,080 hours."
  },
  {
   "id": "search-city-country",
   "say": "Jobs in Toronto.",
   "calls": [
    {
     "tool": "search_jobs",
     "args": {
      "filters": {
       "city": "Toronto",
       "country": "CA"
      },
      "limit": 10
     }
    }
   ],
   "expect": "jobs",
   "rule": "Add country for a city outside the U.S. CA as a country is Canada."
  },
  {
   "id": "search-province",
   "say": "Jobs in Ontario, Canada.",
   "calls": [
    {
     "tool": "search_jobs",
     "args": {
      "filters": {
       "state": "ON",
       "country": "CA"
      },
      "limit": 10
     }
    }
   ],
   "expect": "jobs",
   "rule": "A non-U.S. state or province needs country too; state=ON alone would mean a U.S. state."
  },
  {
   "id": "search-part-time-city",
   "say": "Part-time jobs in New York City.",
   "calls": [
    {
     "tool": "search_jobs",
     "args": {
      "filters": {
       "employment_type": "part_time",
       "city": "New York",
       "state": "NY"
      },
      "limit": 10
     }
    }
   ],
   "expect": "jobs",
   "rule": "employment_type is an exact value such as full_time or part_time."
  },
  {
   "id": "search-hybrid-title",
   "say": "Hybrid product manager roles.",
   "calls": [
    {
     "tool": "search_jobs",
     "args": {
      "filters": {
       "title": "product manager",
       "work_arrangement": "hybrid"
      },
      "limit": 10
     }
    }
   ],
   "expect": "jobs",
   "rule": "work_arrangement is remote, hybrid or in_person."
  },
  {
   "id": "search-description",
   "say": "Jobs that mention Kubernetes.",
   "calls": [
    {
     "tool": "search_jobs",
     "args": {
      "filters": {
       "description": "kubernetes"
      },
      "limit": 10
     }
    }
   ],
   "expect": "jobs",
   "rule": "description searches the job text; q searches title or description."
  },
  {
   "id": "search-description-bool",
   "say": "Jobs that need Python but not Java.",
   "calls": [
    {
     "tool": "search_jobs",
     "args": {
      "filters": {
       "description_advanced": "python AND NOT java"
      },
      "limit": 10
     }
    }
   ],
   "expect": "jobs",
   "rule": "description_advanced takes AND, OR, NOT and parentheses."
  },
  {
   "id": "search-keyword",
   "say": "Anything about machine learning.",
   "calls": [
    {
     "tool": "search_jobs",
     "args": {
      "filters": {
       "q": "machine learning"
      },
      "limit": 10
     }
    }
   ],
   "expect": "jobs",
   "rule": "q is a phrase in the title or description, ranked by relevance."
  },
  {
   "id": "search-current",
   "say": "Only show jobs that are still open.",
   "calls": [
    {
     "tool": "search_jobs",
     "args": {
      "filters": {
       "title": "accountant",
       "currentness": "current"
      },
      "limit": 10
     }
    }
   ],
   "expect": "jobs",
   "rule": "currentness=current (or active=true) keeps jobs the latest read still found."
  },
  {
   "id": "search-not-stale",
   "say": "Leave out stale jobs.",
   "calls": [
    {
     "tool": "search_jobs",
     "args": {
      "filters": {
       "title": "accountant",
       "stale": false
      },
      "limit": 10
     }
    }
   ],
   "expect": "jobs",
   "rule": "stale=false filters stale jobs out."
  },
  {
   "id": "search-source",
   "say": "Jobs from Greenhouse boards only.",
   "calls": [
    {
     "tool": "search_jobs",
     "args": {
      "filters": {
       "source": "greenhouse"
      },
      "limit": 10
     }
    }
   ],
   "expect": "jobs",
   "rule": "source is the vendor name in lower case."
  },
  {
   "id": "search-has-pay",
   "say": "Marketing jobs that list a salary.",
   "calls": [
    {
     "tool": "search_jobs",
     "args": {
      "filters": {
       "title": "marketing",
       "has_pay": true
      },
      "limit": 10
     }
    }
   ],
   "expect": "jobs",
   "rule": "has_pay=true keeps jobs with a posting that publishes pay."
  },
  {
   "id": "search-apply-open",
   "say": "Only jobs where I can still apply.",
   "calls": [
    {
     "tool": "search_jobs",
     "args": {
      "filters": {
       "title": "nurse",
       "application_check": "available"
      },
      "limit": 10
     }
    }
   ],
   "expect": "jobs",
   "rule": "application_check is available, closed, broken or inconclusive; available means an application could still be started."
  },
  {
   "id": "count-broken-apply",
   "say": "How many jobs have a broken application link?",
   "calls": [
    {
     "tool": "count_jobs",
     "args": {
      "filters": {
       "application_check": "broken"
      }
     }
    }
   ],
   "expect": "count_zero",
   "rule": "Expect 0. A broken or closed apply check takes that posting out of the current set, so a job with no other current posting is withdrawn and never reaches the public data. A count above 0 would mean withdrawn jobs are leaking into the public set. To find jobs whose apply link is still open, use application_check \"available\"."
  },
  {
   "id": "search-removed",
   "say": "Jobs that were taken down.",
   "calls": [
    {
     "tool": "search_jobs",
     "args": {
      "filters": {
       "posting_status": "no_longer_listed"
      },
      "limit": 10
     }
    }
   ],
   "expect": "jobs",
   "rule": "posting_status=no_longer_listed means a complete read of the source no longer found the posting."
  },
  {
   "id": "search-changed",
   "say": "What changed since yesterday?",
   "calls": [
    {
     "tool": "search_jobs",
     "args": {
      "filters": {
       "updated_since": "{{today-1}}"
      },
      "sort": "updated",
      "limit": 10
     }
    }
   ],
   "expect": "jobs",
   "rule": "updated_since with sort=updated is the incremental pull."
  },
  {
   "id": "search-next-page",
   "say": "Show me the next page.",
   "calls": [
    {
     "tool": "search_jobs",
     "args": {
      "filters": {
       "title": "nurse"
      },
      "limit": 5
     }
    },
    {
     "tool": "search_jobs",
     "args": {
      "filters": {
       "title": "nurse"
      },
      "limit": 5,
      "cursor": "{{prev.cursor}}"
     }
    }
   ],
   "expect": "jobs",
   "rule": "Repeat the same filters with the cursor from the last result."
  },
  {
   "id": "get-job",
   "say": "Tell me everything about that job.",
   "calls": [
    {
     "tool": "search_jobs",
     "args": {
      "filters": {
       "title": "pharmacist"
      },
      "limit": 1
     }
    },
    {
     "tool": "get_job",
     "args": {
      "job_id": "{{prev.job_id}}"
     }
    }
   ],
   "expect": "job",
   "rule": "get_job returns one job with every linked posting and the full description."
  },
  {
   "id": "get-job-source",
   "say": "Show me the raw source data for that job.",
   "calls": [
    {
     "tool": "search_jobs",
     "args": {
      "filters": {
       "title": "pharmacist"
      },
      "limit": 1
     }
    },
    {
     "tool": "get_job",
     "args": {
      "job_id": "{{prev.job_id}}",
      "include_source_data": true
     }
    }
   ],
   "expect": "job",
   "rule": "include_source_data adds each posting's source fields."
  },
  {
   "id": "full-descriptions",
   "say": "Give me the full descriptions, not snippets.",
   "calls": [
    {
     "tool": "search_jobs",
     "args": {
      "filters": {
       "title": "paralegal"
      },
      "limit": 3,
      "descriptions": "full"
     }
    }
   ],
   "expect": "jobs",
   "rule": "Descriptions are cut to 400 characters unless descriptions=full."
  },
  {
   "id": "file-export",
   "say": "Export the first 200 nurse jobs in Ohio as a file.",
   "calls": [
    {
     "tool": "search_jobs",
     "args": {
      "filters": {
       "title": "nurse",
       "state": "OH"
      },
      "deliver_file": true,
      "max_jobs": 200
     }
    }
   ],
   "expect": "file",
   "rule": "For more than about 100 jobs use deliver_file with max_jobs instead of paging 25 at a time."
  },
  {
   "id": "file-read",
   "say": "Read the next 25 jobs from that file.",
   "calls": [
    {
     "tool": "search_jobs",
     "args": {
      "filters": {
       "title": "nurse",
       "state": "OH"
      },
      "deliver_file": true,
      "max_jobs": 200
     }
    },
    {
     "tool": "read_file",
     "args": {
      "file_id": "{{prev.file_id}}",
      "offset": 25,
      "limit": 25
     }
    }
   ],
   "expect": "file_page",
   "rule": "read_file pages through a delivered file for free for 24 hours."
  },
  {
   "id": "usage-jobs",
   "say": "How many jobs do I have left this month?",
   "calls": [
    {
     "tool": "get_usage",
     "args": {}
    }
   ],
   "expect": "usage",
   "rule": "get_usage is free and works even when the allowance is used up."
  },
  {
   "id": "usage-requests",
   "say": "How many API requests have I used?",
   "calls": [
    {
     "tool": "get_usage",
     "args": {}
    }
   ],
   "expect": "usage",
   "rule": "The same call reports requests used and remaining."
  },
  {
   "id": "fields-pay",
   "say": "What filters are there for pay?",
   "calls": [
    {
     "tool": "list_fields",
     "args": {
      "keywords": [
       "pay"
      ]
     }
    }
   ],
   "expect": "fields",
   "rule": "list_fields is free; pass keywords to narrow it."
  },
  {
   "id": "docs-overage",
   "say": "What happens when I go over my plan?",
   "calls": [
    {
     "tool": "search_docs",
     "args": {
      "question": "What happens when I reach my plan's limit?"
     }
    }
   ],
   "expect": "docs",
   "rule": "Questions about plans, pricing, limits and setup go to search_docs, which is free."
  },
  {
   "id": "docs-setup",
   "say": "How do I connect Headcount Labs to Claude?",
   "calls": [
    {
     "tool": "search_docs",
     "args": {
      "question": "How do I connect the MCP server to Claude?"
     }
    }
   ],
   "expect": "docs",
   "rule": "Setup questions go to search_docs."
  },
  {
   "id": "confirm-level",
   "say": "Stop asking me before big searches.",
   "calls": [
    {
     "tool": "set_confirmation_level",
     "args": {
      "percent": 0
     }
    },
    {
     "tool": "set_confirmation_level",
     "args": {
      "percent": 25
     }
    }
   ],
   "expect": "level",
   "rule": "Only when the user asks. 0 turns the question off; the runner puts it back to 25."
  },
  {
   "id": "overage-on",
   "say": "Turn on overage.",
   "calls": [
    {
     "tool": "set_overage",
     "args": {
      "enabled": true
     }
    }
   ],
   "expect": "not_run",
   "rule": "Only when the user asks. It changes billing, so the runner does not call it; on the free plan it returns an upgrade_url."
  },
  {
   "id": "overage-limit",
   "say": "Don't let overage cost more than $25 a month.",
   "calls": [
    {
     "tool": "set_overage",
     "args": {
      "monthlyLimitUsd": 25
     }
    }
   ],
   "expect": "not_run",
   "rule": "monthlyLimitUsd caps overage dollars a month; null clears it, and leaving it out keeps the current limit. Only when the user asks; the runner does not call it."
  },
  {
   "id": "search-with-company",
   "say": "Show Salesforce jobs with the company details.",
   "calls": [
    {
     "tool": "search_jobs",
     "args": {
      "filters": {
       "company": "salesforce",
       "include": "company"
      },
      "limit": 3
     }
    }
   ],
   "expect": "jobs",
   "rule": "include=company adds the linked company record to each job."
  },
  {
   "id": "no-tool-salary",
   "say": "What's the average salary for nurses?",
   "calls": [],
   "expect": "no_tool",
   "rule": "No MCP tool answers this yet. Say so; market statistics are coming to paid plans. Do not average a sample of search results and present it as the market figure."
  },
  {
   "id": "no-tool-company",
   "say": "Look up Salesforce's company record.",
   "calls": [],
   "expect": "no_tool",
   "rule": "The MCP has no company tool yet. The REST API has GET /v1/companies; search_jobs with include=company adds the company record to each job."
  }
 ],
 "tested": "2026-10-09T15:35:31.538244Z",
 "results": [
  {
   "id": "count-all",
   "pass": true,
   "seconds": [
    5.61
   ]
  },
  {
   "id": "count-title-state",
   "pass": true,
   "seconds": [
    1.28
   ]
  },
  {
   "id": "count-company-open",
   "pass": true,
   "seconds": [
    0.29
   ]
  },
  {
   "id": "search-remote",
   "pass": true,
   "seconds": [
    0.53
   ]
  },
  {
   "id": "search-senior",
   "pass": true,
   "seconds": [
    0.51
   ]
  },
  {
   "id": "search-company",
   "pass": true,
   "seconds": [
    0.45
   ]
  },
  {
   "id": "search-recent-state",
   "pass": true,
   "seconds": [
    0.21
   ]
  },
  {
   "id": "search-pay-min",
   "pass": true,
   "seconds": [
    3.01
   ]
  },
  {
   "id": "search-city-country",
   "pass": true,
   "seconds": [
    0.23
   ]
  },
  {
   "id": "search-province",
   "pass": true,
   "seconds": [
    0.14
   ]
  },
  {
   "id": "search-part-time-city",
   "pass": true,
   "seconds": [
    0.57
   ]
  },
  {
   "id": "search-hybrid-title",
   "pass": true,
   "seconds": [
    4.68
   ]
  },
  {
   "id": "search-description",
   "pass": true,
   "seconds": [
    1.45
   ]
  },
  {
   "id": "search-description-bool",
   "pass": true,
   "seconds": [
    0.19
   ]
  },
  {
   "id": "search-keyword",
   "pass": true,
   "seconds": [
    0.79
   ]
  },
  {
   "id": "search-current",
   "pass": true,
   "seconds": [
    0.27
   ]
  },
  {
   "id": "search-not-stale",
   "pass": true,
   "seconds": [
    0.48
   ]
  },
  {
   "id": "search-source",
   "pass": true,
   "seconds": [
    0.17
   ]
  },
  {
   "id": "search-has-pay",
   "pass": true,
   "seconds": [
    1.73
   ]
  },
  {
   "id": "search-apply-open",
   "pass": true,
   "seconds": [
    3.5
   ]
  },
  {
   "id": "count-broken-apply",
   "pass": true,
   "seconds": [
    0.11
   ]
  },
  {
   "id": "search-removed",
   "pass": true,
   "seconds": [
    0.11
   ]
  },
  {
   "id": "search-changed",
   "pass": true,
   "seconds": [
    0.11
   ]
  },
  {
   "id": "search-next-page",
   "pass": true,
   "seconds": [
    0.64,
    0.59
   ]
  },
  {
   "id": "get-job",
   "pass": true,
   "seconds": [
    0.24,
    0.09
   ]
  },
  {
   "id": "get-job-source",
   "pass": true,
   "seconds": [
    0.2,
    0.08
   ]
  },
  {
   "id": "full-descriptions",
   "pass": true,
   "seconds": [
    0.25
   ]
  },
  {
   "id": "file-export",
   "pass": true,
   "seconds": [
    2.38
   ]
  },
  {
   "id": "file-read",
   "pass": true,
   "seconds": [
    1.06,
    0.06
   ]
  },
  {
   "id": "usage-jobs",
   "pass": true,
   "seconds": [
    0.06
   ]
  },
  {
   "id": "usage-requests",
   "pass": true,
   "seconds": [
    0.07
   ]
  },
  {
   "id": "fields-pay",
   "pass": true,
   "seconds": [
    0.14
   ]
  },
  {
   "id": "docs-overage",
   "pass": true,
   "seconds": [
    0.03
   ]
  },
  {
   "id": "docs-setup",
   "pass": true,
   "seconds": [
    0.03
   ]
  },
  {
   "id": "confirm-level",
   "pass": true,
   "seconds": [
    0.04,
    0.04
   ]
  },
  {
   "id": "overage-on",
   "pass": null,
   "seconds": []
  },
  {
   "id": "overage-limit",
   "pass": null,
   "seconds": []
  },
  {
   "id": "search-with-company",
   "pass": true,
   "seconds": [
    0.4
   ]
  },
  {
   "id": "no-tool-salary",
   "pass": null,
   "seconds": []
  },
  {
   "id": "no-tool-company",
   "pass": null,
   "seconds": []
  }
 ]
}