Juicebox

Answers general questions about how Juicebox works from its canonical product guide: objects and relationships, sourcing agents, project and candidate statuses, capacity and limits, settings, and where features live in the app. Answers are grounded in the guide and state when something is not documented. Use it for product-knowledge questions. It is read-only and does not read live project, candidate, or settings data (those tools are the source of truth). Plan-gated questions use the same plan whoami already returns for this connection.

answer_product_question

Check whether an agent that create_agent kicked off has finished setting up. Pass `agentId`. Reports the agent's actual live status — it never inspects the candidate pool. Returns one of: status 'busy' — the agent is still calibrating its search (call again in ~a minute); status 'sourcing' — it's calibrated and sourcing candidates, so you're done (the message describes its actual outreach); status 'trial_completed' (success) — a free-trial agent finished and sourced its trial batch (call start_sourcing to run again once a slot is free); or status 'action_required' (isError) — it isn't sourcing and can't start on its own, with a `reason`: 'paused' (resume it with manage_agent), 'closed' (reopen it with manage_agent), 'run_failed' (its last run failed — review it on the web), 'start_failed' (it calibrated but is idle, so auto-source was refused — call start_sourcing, which reports the exact blocker, e.g. the org agent limit; no need to recalibrate), 'calibration_failed' (the setup turn itself failed — just retry create_agent with the same agentId and context), 'lookup_failed' (a transient read error, not an agent problem — call check_agent_status again in a few seconds), 'question' (it asked the user something), or 'needs_more_info' (otherwise stalled). On 'action_required', tell the user to open the agent on the web at the returned `agentUrl` to finish — EXCEPT 'start_failed' (retry via start_sourcing), 'calibration_failed' (retry create_agent), and 'lookup_failed' (retry check_agent_status). After create_agent, poll this every ~60s while it reports 'busy', for AT MOST ~10 polls — if it's still 'busy' after ~10 minutes, STOP polling and direct the user to the agent's URL to check on the web. Once the status is anything other than 'busy', STOP polling this agent — do not call this tool again for it unless the user asks for a fresh check (a sourcing agent stays sourcing; there is nothing to watch). Polling far past that is refused with error 'poll_limit_reached'. Read-only — it never changes the agent.

check_agent_status

Create a new sourcing agent and kick off its calibration, or (re)calibrate an existing one by passing its `agentId`. To build a search the agent NEEDS three must-haves, which you pass as structured inputs: `jobTitle` (the role/function), `location`, and `yearsOfExperience` (a minimum is fine). If any of the three is missing this tool returns status 'needs_info' with a `missing` list and starts nothing — collect them from the user first, then call again. `context` is optional extra detail (a full JD, must-have skills, industry). With all three present, this tool creates the agent (when no `agentId`) and kicks off a calibration setup turn in the BACKGROUND, returning status 'calibrating' immediately (the turn runs longer than a tool call can block). It does NOT return the calibration result — check it with the separate check_agent_status tool, polling every ~60s while it reports 'busy', for AT MOST ~10 polls. If it's still 'busy' after ~10 minutes, STOP polling and direct the user to the agent's URL to check on the web. Once it reports anything other than 'busy', stop polling that agent entirely. When calibration succeeds and yields a viable search, the agent AUTO-SOURCES (outreach defaults to Shortlist + manual approval — no separate start_sourcing needed). If the agent instead has a question or the brief was too thin, check_agent_status reports 'action_required' and points the user to the agent's URL to finish on the web. Recalibrating an agent that has ALREADY started sourcing is refused (status 'already_sourcing', nothing runs) — its search is locked in for its runs, so manage it in the app instead. Returns the agentId and the agent's URL. Call get_agent_schema first.

create_agent

Describe how to create, calibrate, and run a Juicebox sourcing agent: the required and optional inputs, how calibration works, org constraints, the agent lifecycle (start / pause / resume / close / reopen), and what is not yet configurable. It is the schema tool to call before create_agent / start_sourcing / manage_agent. Its guidance also covers what a complete brief needs (a job description or role requirements) when the provided input is incomplete.

get_agent_schema

Return the analytics catalog: tables, query fields (dimensions + metrics), joins, limits, rules, and examples. Call this first, then build a query for get_data using the exact qualified field names (table.field) it returns. Read-only; results are always scoped to your organization. Max 100 rows are returned per get_data call.

get_schema

Report your organization's export-credit balance for the current billing period, when that period ends, and when credits next refresh. Read-only; org-scoped. Export credits are the budget `get_candidate_details` spends: hydrating a candidate not yet exported this period (which reveals their full experience history) draws down this balance (already-exported candidates are free). Call this to see how many candidate reveals are left before that tool starts rejecting calls, and use `preview_candidate_details_cost` to price a specific batch. Returns: { limit, remaining, used, mode, periodEnd, periodEndISO, resetsAt, resetsAtISO, refreshes[] } where "limit" is the period's total export credits, "remaining" the credits still available, "used" = limit − remaining, "mode" the billing cadence ("monthly" | "annual" | "rolling"), "periodEnd"/"periodEndISO" when the current billing period ends (unix seconds / ISO string; null on a rolling window with no fixed subscription period), "resetsAt"/"resetsAtISO" the NEXT credit refresh (null when nothing is pending), and "refreshes" every upcoming { date, credits } return so remaining + Σ credits = limit. Rolling plans return credits per contact 30 days after each export, so multiple refresh rows are normal.

get_export_credits

Read a single Juicebox project's intake notes — the role brief from the intake meeting with the hiring manager — as markdown. Read-only; scoped to your organization and to projects you can access. Meeting transcripts are never returned. Call `resolve` (type "project") first to turn a project name or /project/{id} URL into a projectId, then pass it here (a /project/{id} URL is also accepted directly). Returns: { success, projectId, status, notes, truncated, updatedAt, intakeUrl } where - status → notes pipeline state: "draft", "processing", "running", "complete", or "error" (null on a legacy intake). While "processing" or "running", `notes` is still the previous version and updatedAt already reflects the new run; re-read once it settles - notes → the published notes as markdown, citation markers stripped - truncated → true when the notes were cut short; open intakeUrl for the full text - updatedAt → ISO 8601 timestamp of the last change, or null - intakeUrl → link to the intake page in Juicebox A project you cannot access, or one with no intake, returns { success: false, error_code: "not_found" }; an intake with no notes yet adds reason "no_notes" and its pipeline status so callers can retry while processing. Neither is an error. Availability: Business plan only, and only for projects you can access.

get_intake_notes

Summarize a single Juicebox project: its metadata plus how much is in it (saved searches + shortlisted candidates). Read-only; scoped to your organization and to projects you can access. Call `resolve` (type "project") first to turn a project name or /project/{id} URL into a projectId, then pass it here (a /project/{id} URL is also accepted directly). Returns: { success, projectId, name, status, closed, isConfidential, hasAgent, agentKind, ownerId, ownerName, collaboratorCount, createdAt, lastUpdatedAt, counts: { savedSearches, shortlistedCandidates }, warnings? } where - name → project display name (role title), or null if untitled - status → lifecycle status string; "closed" is its boolean form - isConfidential → true when the project is restricted to owner + collaborators - hasAgent → true when an agent is attached; agentKind is "current", "agentic", or null - ownerId → the owner's internal user id (for linking, not for display) - ownerName → the owner's display name to show the user, or null if it can't be resolved - collaboratorCount → how many teammates the project is shared with - createdAt / lastUpdatedAt → ISO 8601 timestamps - counts.savedSearches → number of active (non-archived) saved searches on the project - counts.shortlistedCandidates → number of candidates currently on the project's shortlist (matches search_shortlist) A count is null (never 0) when its backend couldn't be read; the reason is listed in "warnings". Use this for "how many searches / candidates does project X have?" and to confirm a project before drilling in with search_shortlist or get_data. Availability: Business plan only, and only for projects you can access.

get_project

⚠️ THIS TOOL SPENDS EXPORT CREDITS. Hydrate a batch of shortlisted candidates by contactId, returning every profile field search_shortlist withholds: current title & company, location, skills, years of experience / tenure, and the FULL experience/education history (search_shortlist only gives you name + LinkedIn URL). Only contacts in your organization are returned. Pass a focused batch (max 25). EXPORT CREDITS (this tool SPENDS them) — because it reveals a candidate's full experience history, hydrating a candidate that has NOT been exported this billing period CONSUMES one export credit and marks that contact exported (so hydrating them again later is free). Already-exported candidates cost nothing. The charge is all-or-nothing: if your remaining balance is less than the number of un-exported candidates in the batch, the call is REJECTED with error_code "not_enough_credits" and spends nothing — reduce the batch or top up. To see the cost BEFORE calling, use `preview_candidate_details_cost` (same args, read-only, spends nothing); use `get_export_credits` for the overall balance and reset date. Typical flow: resolve project → search_shortlist(projectId, <indexed filters>) → take contactIds → preview_candidate_details_cost(projectId, contactIds) → get_candidate_details(projectId, contactIds) → filter/aggregate the un-indexed attribute. Requires a projectId (the shortlist the contacts belong to): access is enforced AND only contacts actually on that project's shortlist are hydrated, so pass the ids from search_shortlist on the same project. Returns, per contact: { contactId, fullName, linkedinUrl, alreadyExported, creditConsumed, currentTitle, currentCompany, location, yearsOfExperience, totalExperienceMonths, averageTenureMonths, skills, experience[], education[] } plus { requested, returned, missing, exportCredits, disclaimer }. "alreadyExported" is true when the candidate was exported before this call (free); "creditConsumed" is true when this call spent a credit on them. "missing" lists contactIds not on this project's shortlist or with no resolvable profile (treat their attributes as unknown, not zero); missing candidates are never charged. "exportCredits" reports the balance AFTER this call plus creditsConsumed. COMPENSATION (opt-in, costs NO extra credit) — pass `includeCompensation: true` to also get each candidate's estimated annual compensation: the same AI estimate the Juicebox candidate profile shows, derived from market data for their company/title/level/location. It is an ESTIMATE, not the candidate's actual pay — say so when you report it. Estimates are usually LLM-grounded in multiple market datapoints; occasionally (when that grounding fails) a limited-data approximation derived from a single reference datapoint is returned in the same shape. Pricing is unchanged: compensation rides on the reveal credit this tool already charges (and is free for already-exported candidates), so `preview_candidate_details_cost` stays accurate. Because estimating is slow, batches are capped at 10 contactIds when this flag is set. Each candidate's `compensation` field is one of: an estimate object (min/max total yearly compensation plus an `explanation`); `null` — no market data for that company, or no estimate could be grounded (FINAL, do not retry); or `{ status: "pending" }` — still being computed in the background, or deferred; when deferral is due to your per-user estimate rate limit — separate from the org-wide export credits — the pending object carries `retryAfterSeconds`, and re-polling sooner cannot start work. To collect pending ones, simply CALL THIS TOOL AGAIN with the same ids (free — they're already exported now) and read the estimate off the second result; if a candidate is still pending after two such retries, treat their compensation as unavailable and move on. The top-level `compensationPending` array lists exactly which contactIds are worth re-requesting. `compensationPending` and its companion note are OMITTED entirely when nothing is pending — test for their presence, don't wait for an empty array. SCOPE — this only hydrates candidates on this project's shortlist (contacts a recruiter explicitly saved), never the full candidate pool or the whole org. The `disclaimer` field restates this; surface that limitation to the end user rather than implying these are all candidates. Notes: yearsOfExperience is derived from totalExperienceMonths (÷12); null means the candidate has no enrichment (unknown), not zero. For precise aggregates over LARGE sets, the analytics tool (get_data) exposes tenure directly and avoids row-by-row math. Contact info (emails/phone) and diversity/gender attributes are intentionally NOT returned.

get_candidate_details

List candidates on a project's shortlist, with optional server-side filters on INDEXED fields. Read-only; scoped to your organization and to projects you can access. Call `resolve` (type "project") first to turn a project name or /project/{id} URL into a projectId, then pass it here. Supported filters (each is a list; values within one filter are OR'd, different filters are AND'd): - skills → candidates whose skills include the given value(s) - company → worked at the company (current or past) - currentCompany → currently at the company - title → held the job title (current or past) - currentTitle → current job title - university → attended the school - major → field of study - location → located in Also supports a free-text `query` (name/company/title/school) and a `statusId` (pipeline stage). Max 25 per call — paginate with `page` for larger shortlists. WHAT IT RETURNS — identity only: a page of { contactId, fullName, linkedinUrl } plus { count, page, hasMore, disclaimer }. Name + LinkedIn URL are free and not metered. It returns NOTHING else about the candidate: no current title/company, location, skills, tenure, or experience/education history. Every other profile field is served exclusively by `get_candidate_details` — pass the `contactId` there to hydrate them. Revealing an un-exported candidate via get_candidate_details CONSUMES an export credit (price a batch first with `preview_candidate_details_cost`). NOTE — you can still FILTER server-side on the fields above (skills, companies, titles, schools, majors, location); those just aren't echoed back in the result. Use the filters to narrow the shortlist, then pass the returned contactIds to `get_candidate_details` for the actual attribute values. SCOPE — results are ONLY candidates on this project's shortlist (contacts a recruiter explicitly saved), never the full candidate pool, sourced/searched results, or the whole org. The `disclaimer` field restates this; surface that limitation to the end user rather than implying these are all candidates.

search_shortlist