List the saved searches on a Juicebox project (searchId + name). Saved searches are stable and re-runnable, so this is the entry point for pulling existing sourcing work. Defaults to the configured project.

Pull a saved search's ranked candidates — up to ~500 in one call. Returns name, LinkedIn URL, title, company, location, a numeric matchRate (0-100, banded) and per-criterion verdicts. Costs NO export credits: this is the same free surface the results page renders.

READING THE RESULTS: at the top of a ranked list every candidate meets every criterion, so criteria-met count does NOT discriminate up there — use matchRate and depth. A criterion with verdictFound=false is reported as result "unknown": that means no evidence was found, NOT that the candidate fails it. Never treat an unknown as a negative.

If the search has never been executed, this errors — open it in the app and press "Run search" once.

Size a filter set WITHOUT running a search — the tuning primitive. Free and side-effect free, so permute filters and compare before committing to a run. The endpoint is VERIFIED DETERMINISTIC (same body, same count on repeat), which is what makes the comparisons below trustworthy.

queryInput is a PATCH, not a whole body. It is merged over a ~164-key template harvested live from a saved search, because a PARTIAL body does not error — it returns result:0, which reads exactly like "nobody matches your filters". Pass only the keys you want to change. Use searchId to choose which saved search supplies the template; the response echoes baseline (the unpatched count).

ALWAYS CHECK noEffect IN THE RESPONSE. Unrecognised keys and wrong value shapes are dropped SILENTLY, so an unchanged count means the key name is probably wrong, NOT that the filter does not matter. Measured example: coSizes (company headcount) is ignored in all eight shapes tried, including [{name:"51-200"}], ["51-200"], [{title,tag}] and [{min,max}]. Its real shape is still unknown — set the filter in the Juicebox UI and capture the request before trusting it.

SOME FILTERS EXPAND RATHER THAN RESTRICT, which is the opposite of the intuition and was measured on one search (baseline 1413): dropping industries gives 1387 and dropping coTags gives 1247 — REMOVING them SHRINKS the pool, so they act as OR-expanders and cannot be used to narrow onto a category. An unrecognised industry ("mining & metals") returns the same 1387 as an empty list. What actually restricts: skills (removing all four widened 1413 to 4526), yearsOfExp (20 gives 881), selectedLocs, and criteria. Note this REVISES the older claim that broad skill terms widen the pool — specific skills restrict hard, broad ones merely fail to restrict. The practical rule is unchanged: drop skill terms that describe the whole population, and promote the ONE hard requirement to a skill (e.g. "AI Agents", not prose about being AI-first).

CREATE and RUN a new Juicebox search from a natural-language prompt, then return its ranked candidates. This is the ONLY tool here that WRITES: it leaves a real saved search in the workspace, visible to the whole seat. Confirm with the user before calling it, and do not call it speculatively in a loop — each call is a persistent object someone has to look at.

THE PROMPT IS THE CONTROL SURFACE, and it beats filter tuning. Juicebox extracts filters from the prompt and does it well: "roughly $10M to $100M revenue" became revenueRanges ["$10m-$25m","$25m-$50m","$50m-$100m"], and "exclude enterprise megacaps and independent consultants" became an extra ranking criterion. Measured head-to-head against the best hand-tuned search on the same intent, the prompt-built one returned 42/44 usable candidates versus 22/30. So state the company shape, the geography, the seniority, the number the person must own, and what to EXCLUDE, in plain prose.

WRITE THE EXCLUSIONS EXPLICITLY. Two pollution categories dominate this market and both respond to being named: enterprise mega-caps (a "VP CS" at Microsoft or IBM owns a structurally different job) and independent consultants / fractional advisors / founders of CS consultancies.

DO NOT tune for a small pool. Pool size and top-of-list quality are uncorrelated — the better of two measured searches had 3.4x the pool. Tune for ranking, not reach.

matchRate is NOT comparable ACROSS searches: it is scored against each search's own criteria, so a stricter criteria set produces LOWER scores on BETTER people. Only the ordering within one search means anything.