answer_product_question
ChatGPTAnswers 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.
check_agent_status
ChatGPTCheck 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.
create_agent
ChatGPTCreate 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.
get_agent_schema
ChatGPTDescribe 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_candidate_details
ChatGPT⚠️ 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 …
get_data
ChatGPTRun a structured, read-only analytics query and return result rows. Call get_schema first for the exact table/field names. Query shape: { from: { table }, joins?, select: string[], filters?, dateRange?, orderBy?, limit? }. select is a flat list of qualified field names (table.field): name dimensions to break down and metrics to measure — the server aggregates and groups automatically. Org scope is always applied; never add an org filter. To scope to one project, filter on its projectId/project_id — call the resolve tool (type "project") to turn a project name or URL into an id first. To filter by a specific teammate or sequence you only know by name, resolve it to an id first with the resolve tool (type "teammate" or "sequence"). Returns at most 100 rows; the "truncated" flag signals the cap was hit.
get_export_credits
ChatGPTReport 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_intake_notes
ChatGPTRead 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_project
ChatGPTSummarize 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_schema
ChatGPTReturn 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_sequence_run_emails
ChatGPTRead one sequence run's outreach thread — the emails the sequence sent plus the replies on both sides — by sequenceRunId. Read-only; scoped to your organization. Get a sequenceRunId from get_data on the sequence_runs table (select the sequenceRunId dimension). Field names, types and their meanings are declared in this tool's output schema. What the schema cannot tell you: - Bodies and snippets are plain text with links kept as markdown [text](url). A LinkedIn connection request sent without a message, and a call step (whose stored body is the script, not a transcript), both have an empty body. So does a LinkedIn reply whose notification only announced the message and left the text on LinkedIn — an empty body there means unavailable, never that the candidate wrote nothing. - Omit messageIndex to list the thread as metadata + snippets; set it to one message's index to read that body in full. - Messages are ordered oldest → newest, and index is positional within a call. Errors: an out-of-range messageIndex returns error_code "message_out_of_range" with the valid range. Availability: Business plan only, and only for sequences you can access.
manage_agent
ChatGPTManage an existing agent's lifecycle via a single action: - pause: stop an actively-sourcing agent from surfacing new leads / sending outreach (fails 'not_sourcing' if it hasn't started, 'agent_closed' if closed). Resume it later. - resume: un-pause a paused agent so it sources again (no-op if not paused; does NOT apply to closed agents — reopen instead — or trial-completed agents — use start_sourcing). A wedged first run re-triggers immediately and a repaired config pause starts today's run right away; a plain pause waits for the next scheduled run. A still-broken sequence config is re-validated and refused until repaired. - close: stops the agent, tears down its schedule, and frees its agent slot; optionally also stops in-flight outreach sequence runs (set cancelPendingSequences). NOT permanent — reopen moves a closed agent back to configuring to undo it. Because close interrupts active sourcing and frees the slot, it is normally confirmed with the user before use. - reopen: move a CLOSED agent back to configuring so it can be recalibrated (create_agent) and restarted (start_sourcing). Reopening does not itself consume a slot or start sourcing. Requires the same org create-Agents permission as create_agent (fails 'forbidden' if the user isn't on the org's agent allowlist). Requires the agent's agentId (use the resolve tool with type "agent" if you only have its name). Returns the resulting state.
ping
ChatGPTHealth check. Returns pong so clients can verify the connection.
preview_candidate_details_cost
ChatGPTPreview how many export credits a get_candidate_details call WOULD consume for a batch of contactIds, WITHOUT revealing anything or spending a credit. Read-only; org-scoped; takes the same { projectId, contactIds } as get_candidate_details. get_candidate_details charges one export credit per candidate whose full experience history it reveals and who has NOT been exported this billing period; already-exported candidates and contactIds not on the shortlist are free. This tool computes that cost up front so you can size the batch before committing. Returns: { projectId, requested, onShortlist, notOnShortlist[], alreadyExported, creditsRequired, remaining, sufficient, disclaimer } where "onShortlist" is how many requested contactIds are actually on this project's shortlist (the rest, "notOnShortlist", are not hydrated and never charged), "alreadyExported" how many of those were exported this period (free), "creditsRequired" = onShortlist − alreadyExported (the credits the real call would spend), "remaining" your current balance, and "sufficient" = remaining ≥ creditsRequired. Note this is an upper bound: the real call skips any shortlist member whose profile can't be resolved, which would cost slightly less.
resolve
ChatGPTResolve a name, title, email, or Juicebox URL to its internal id so you can scope a get_data query (or act on an agent). Read-only; only entities you can access are searched. Set "type" to pick what to resolve: - "project": pass a project title or a Juicebox /project/{id} URL → returns { projectId, name }. - "teammate": pass a person's name or email → returns { userId, displayName } (use it for an ownerId/user id filter). - "sequence": pass an outreach sequence title (optionally set projectId to narrow to one project) → returns { sequenceId, title, projectId }. - "agent": pass a sourcing agent's name (its role/title) → returns { agentId, title }. Use the agentId with the agent tools (create_agent, start_sourcing, manage_agent). Requires the agents:write scope. On a unique exact match returns { success: true, exact: true, ... }; otherwise returns candidate "options" (projects include each owner's name) to disambiguate before acting on one. Private sequences and confidential agents you don't own or collaborate on are never matched.
search_shortlist
ChatGPTList 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.
start_sourcing
ChatGPTStart an agent sourcing candidates. Usually NOT needed after create_agent, which auto-sources as soon as the agent is calibrated. Use this to start an agent that was calibrated elsewhere (e.g. in the Juicebox app), to retry after create_agent reported a sourcing error you've since fixed, or to restart a trial-completed agent. The agent must be calibrated first (else 'not_calibrated'). Outreach defaults to Shortlist with manual per-lead approval (each candidate must be reviewed and approved before it's shortlisted; the agent sends no automated emails); these are applied automatically if not already set. Returns the new status.
whoami
ChatGPTReturns a summary of the connected account: email, the connected org's name, plan, whether an org is connected, analytics availability, and granted OAuth scopes.
create_agent
Claudeget_agent_schema
Claudeget_candidate_details
Claudeget_data
Claudeget_project
Claudeget_schema
Claudemanage_agent
Claudeping
Clauderesolve
Claudesearch_shortlist
Claudestart_sourcing
Claudewhoami
Claude