| search_jobs | acts | [metered: one source query per pool] Run a ONE-OFF job search. Results are raw postings and are NEVER scored against the owner's profile. The owner's exclusion lists and stated country are applied to the results unless forSomeoneElse is true. Set forSomeoneElse: true when searching on behalf of somebody else — it turns the owner's standing filters off. Nothing is saved. Prefer create_search when the user wants this run repeatedly. The response reports `truncated` and (when it can) `totalAvailable` — never present a truncated list as the whole market. A one-off is capped at 100 per pool and has no memory, so on a high-volume query it is a SAMPLE; create_search is what keeps up with one over time. count_jobs sizes a query for free. |
| count_jobs | acts | [free — costs NO job credits] How many postings match, without fetching any of them. Use this to size or debug a query before spending on it: it returns the same compiled expression, the same filter warnings and a total, but buys no rows. Iterate here first, then run search_jobs or create_search once the query looks right. |
| list_matches | reads | [free] Scored postings from the owner's pipeline with score + written rationale. Filters: status, minScore, source. By default, matched postings scoring below their search's score threshold are omitted and COUNTED in hiddenBelowThreshold — when that count is non-zero, the list is not the whole pipeline. Pass includeBelowThreshold: true to see them, each marked belowThreshold. view: "pursuing" returns instead the Pursuing screen: every job between Pursue and Applied with its `stage` (queued → drafted → reviewed → final → applied, derived from the studio session and the documents), its one primary `action`, and its `artifacts`. |
| get_job | reads | [free] Full posting detail: JD, score+rationale (with `flags.lean` — leader/doer/analyst shares of what the posting is buying, read from the responsibilities; it never moves the score), history, notes, artifacts. |
| set_job_status | confirm | [free, state-changing — requires confirm: true] Move a posting through the pipeline (matched→pursuing→tailored→applied→screening→interviewing→offer→closed_*, dismissed↔matched). screening = a recruiter screen or phone call; it is optional (applied→interviewing is legal). Two axes, one column: closed_lost = rejected, closed_withdrawn = withdrawn, closed_won = accepted, and the stage reached before closing is read from the history (get_board returns it as `reached`). Illegal transitions are rejected by the server; closed stays closed. |
| rate_job | acts | [free] Rate a posting with a reason code AND a free-text note — the note tunes future scoring. Reasons: wrong_location, wrong_level, wrong_industry, comp_too_low, reputation, not_interested, good_fit, other. |
| tailor_resume | confirm | [metered: tailor quota — requires confirm: true] Queue a ONE-SHOT provenance-guarded tailored resume for a posting: the whole document is rewritten in the background and the artifact lands in the app. Returns an operation id; poll get_operation. When the user wants to see and decide each change, use the STUDIO instead: open_tailoring_session → review_tailoring_session → get_tailoring_session (read the proposals) → decide_tailoring → build_tailored_resume. The studio and this tool produce the same artifacts under the same guards; the studio applies nothing the user did not accept. |
| revise_tailored | confirm | [metered: tailor quota — requires confirm: true] Apply the author’s review decisions to the latest tailored draft (approve-and-decline). A finished tailor’s get_operation result carries `triage`: posting phrases the draft does not use, each verdict-sorted (supported / judgement / unsupported) with evidence from the record, a suggestion, and — when there is a real limit — a `caution` naming what must NOT be claimed (show it beside the item; it binds the revision too). Pass one decision per item id — approve or decline, optionally with the author’s own wording. Only supported/judgement items can be approved; unsupported items are the honest gap list and cannot be worked in. Returns an operation id; poll get_operation. The result lists `declined` (changes refused as untruthful — a correct outcome), `unauthorizedChanges` (model edits outside the approved scope, reverted), and `changedLines` (what actually changed). Every unchanged line ships byte-identical. |
| list_tailoring_sessions | reads | [free] Every tailoring-studio session on the account, newest first: job, status (new | reviewing | reviewed | built), master version, decided/proposal counts, and the built artifact id when there is one. |
| open_tailoring_session | acts | [free] Open (or return) the tailoring-studio session for a job. Starts from the master version marked exemplar, else the latest; pass resumeId (from list_resumes) to start from another version — that REPLACES an existing session on a different version, discarding its proposals and decisions. Returns the session: sections as numbered lines (index, text, role), proposals (empty until reviewed), decisions, the job, and the master. Refuses (409) a job with no stored description or an account with no master. Next: review_tailoring_session. |
| get_tailoring_session | reads | [free] The full studio session for a job: `session.sections[]` each with `lines[]` ({index, text, role}) and `suggestions[]` ({id, kind: reword|add, lineIndex, original, proposed, reason, postingTerms, source, guard: {ok, reason}, styleNotes}) — a suggestion with guard.ok false was HELD BACK by the no-fabrication guards and cannot be accepted; show it with its reason. Also `session.analysis` (posting signal, verified terminology aliases, `headline.proposed`, `layout[]` recommendations — only a section-order one can be applied for the user), `session.decisions`, `session.lineOverrides`, `session.build` after a build, `progress`, `activeOperation` while a review or build runs, and `latestOperation`. Read this after review_tailoring_session finishes, then walk the proposals WITH the user before calling decide_tailoring. |
| review_tailoring_session | confirm | [metered: tailor quota — requires confirm: true] Queue the studio review: one posting analysis (key terms, requirements, verified terminology aliases; on the user’s own model also layout recommendations and a headline), then every section reviewed line by line and role by role, each proposal checked against the record before it is shown. Returns an operation id; poll get_operation until done, then get_tailoring_session. Optional `sections` (indexes) re-reviews only those; `force` re-runs the posting analysis too. Refuses (409) while a review or build is already running. |
| decide_tailoring | acts | [free] Save the user’s decisions on a reviewed session. `decisions`: one per proposal id — accept, decline, or edit with the user’s own `text`. `lineOverrides`: the user’s own wording (`text`) for ANY line, or `omit: true` to leave a line out of this draft (the master is never changed). `headline`: original | proposed | custom (+ text). `sectionOrder`: every section title exactly once, or null to restore the master’s order. `layoutDecisions`: accept/decline a recommendation id (accepting a section-order one applies it). Every piece of user wording is checked against the record as it lands — dates, figures, every number on the line, traceability — and anything refused comes back in `rejected` with the reason and is NOT saved; tell the user why. A proposal the user does not decide is not applied. Refuses (409) while a review is running. Returns the updated session and progress. |
| build_tailored_resume | confirm | [metered: tailor quota — requires confirm: true] Build the document from the session’s decisions: composed by code (undecided proposals are NOT applied), every changed line re-verified, rendered into the user’s own Word file when the master is a .docx, stored as the same artifacts a one-shot tailor produces (tailored resume + optional cover letter), scored, and the job moved to Tailored. Refuses (422) with `problems` naming any line that cannot be traced to the record — fix those with decide_tailoring first. Returns an operation id; poll get_operation (kind tailor_build); the artifact ids are in its result and get_tailored_document reads them back as text. |
| discard_tailoring_session | confirm | [free, state-changing — requires confirm: true] Start over: delete a job’s studio session (its proposals and decisions). Documents already built stay on the job. |
| get_prep_packet | confirm | [metered: prep quota — requires confirm: true] Queue an interview prep packet (research brief, themes, STAR stories, draft-only outreach). |
| get_board | reads | [free] Kanban board snapshot: cards per live status; applied cards carry days-since-applied aging (followUp.due at 5+ days with nothing back). Closed applications are NOT in the columns — `closed` lists them with `outcome` (rejected | withdrawn | accepted) and `reached` (the stage before closing: applied | screening | interviewing | offer), and `outcomes` is the tally (stillOpen, rejected, withdrawn, accepted, daysToHearBack, answeredShare, appliedEver). |
| move_card | confirm | [free, state-changing — requires confirm: true] Move a board card to another column. Identical to set_job_status; provided so board-centric agents find it. |
| list_searches | reads | [free] Saved searches with stored query translation and warnings. |
| create_search | confirm | [metered: recurring scans every cadence — requires confirm: true] Create a saved search that scans automatically from now on, scores every result against the owner's rubric, and applies their exclusion lists. This — not search_jobs — is the tool that carries the full filter set. Set location and a level filter unless the user genuinely wants worldwide, all-levels results — an unfiltered saved search spends money on every run for roles the candidate cannot take. COVERAGE: each run fetches up to 100 postings per source (career sites and job boards separately), and only those added since the previous run — so a saved search keeps up with a busy query over time rather than sampling it, which a single one-off search cannot do. Use count_jobs to size a query first: if it matches far more per run than the cap, narrow it or shorten the cadence. |
| pause_search | confirm | [free, state-changing — requires confirm: true] Pause or resume a saved search. Pausing preserves the scan watermark; searches are never deleted. |
| get_operation | reads | [free] The outcome of something you queued — tailor_resume, get_prep_packet or a score. Those tools return an operation id and nothing else, so without this an agent can START work it can never observe: no way to tell finished from failed, and no way to read the result. Poll this until status is `done` or `error`. A finished TAILOR returns `unevidenced` — what the posting asks for that the record does not evidence. Show that list to the user: the draft never claims those things, and they are the fastest guide to what is worth adding to the accomplishment bank. A finished tailor also names its `renderer`: `into-master` means the .docx was rendered into the user’s own Word file (their fonts, margins, numbering); `mirrored` means the generic layout, with `rendererFallbackReason` saying why — tell the user when `masterIsDocx` is true, because their formatting was not applied. A finished tailor also carries `triage` (feed revise_tailored), `verbatimSections` with `verbatimReasons` (which sections kept the user’s own words and WHY — a deliberate skip, the time budget, or the failure; tell the user the reason, not just the name), the tally `tailoredSections` / `skippedSections` / `failedSections` with `degraded: true` whenever any section failed (a partly-tailored draft must never be presented as fully tailored; a run where nothing could be tailored is an `error`, retryable, not a `done`), `styleNotes` (advisory style observations, never blocking), `orientation` (what the posting is buying — leader / doer / analyst — vs what the draft reads as; order and emphasis only, a mismatch is a flag not a defect), and `strategy` (`single-pass` = one whole-resume call on the user’s own model; `chunked` = per-section, with `strategyFallbackReason` when a single pass fell back). A finished REVISE carries `declined`, `unauthorizedChanges`, and `changedLines` — show `declined` to the user: those are changes refused as untruthful, which is the guard working. A finished STUDIO REVIEW (kind tailor_review) carries the tally `reviewed` / `suggestions` / `heldBack` / `layout` and `layoutSkipped` when layout advice did not run; the proposals themselves are read with get_tailoring_session. A finished STUDIO BUILD (kind tailor_build) carries `artifactId`, `coverLetterArtifactId`, `changedLines` (the receipt of what the author accepted), `unevidenced`, `triage`, `scorecard`, `renderer`, and `studio: true`. |
| list_accomplishments | reads | [free] The accomplishment bank: the record tailoring draws on ALONGSIDE the master resume. A tailored resume may only use figures that appear here or in the master, verbatim — so this is also the list of figures that can legally appear in a draft. |
| add_accomplishments | acts | [free] Add accomplishments to the bank. APPENDS — existing entries are never replaced, and duplicates are skipped, so this is safe to call repeatedly. Widening the bank is the single most effective way to improve tailored resumes: tailoring can only rearrange what it has been given, and a master resume is one compressed snapshot of a career. Keep figures EXACTLY as the user states them ($4.8M stays $4.8M) — a reworded number is unusable, because the provenance guard matches verbatim. One accomplishment per entry. The response reports what was added, skipped and dropped. For a whole LinkedIn history, the app takes the export zip directly under Profile. |
| update_search | confirm | [free, state-changing — requires confirm: true] Edit a saved search: its query, cadence, threshold, or any filter. Send ONLY what you want to change — every filter you do not mention is preserved. (The underlying API replaces the filter object wholesale, so this tool reads the stored search and merges; a client that rebuilt that object from its own inputs would silently DELETE every filter it did not know about.) Use pause_search to stop or resume one; this is for changing what it seeks. |
| run_search_now | confirm | [metered: one source query per pool — requires confirm: true] Run a saved search immediately instead of waiting for its cadence. Optionally reach further back than the watermark with backfillHours (max 168 = 7 days) to pick up postings from before the search existed. A paused search is refused — resume it first. |
| get_search_health | reads | [free] Why is a search returning nothing? Per search and per source: the last run, how many postings came back, how many were new, whether the run failed and why, and the COMPILED query the supplier actually received. This is the tool for diagnosing a quiet search — an empty result and an impossible query look identical from outside, and the compiled expression is what tells them apart. |
| rescore_job | confirm | [metered: score quota — requires confirm: true] Re-score ONE posting against the current rubric. Use after the questionnaire or exclusion lists change, or when a score looks wrong. Returns an operation id — poll get_operation. |
| add_job_note | acts | [free] Attach a note to a posting — a recruiter conversation, a referral, why it was interesting. Notes are first-class: they are what the owner reads later, when the score has stopped being the interesting part. |
| declare_applied | confirm | [free, state-changing — requires confirm: true] Record an application made OUTSIDE Jobably — through a recruiter, a referral, or a company site. Creates the board card if the posting is not already tracked. Idempotent: declaring the same role twice does not duplicate it. |
| get_exclusions | reads | [free] The two standing exclusion lists: `fit` (poor-fit employers, which the rubric could in principle learn) and `reputation` (vetoes that apply regardless of role). These shape every search and every score, so read them before concluding a search is behaving oddly. |
| set_exclusions | confirm | [free, state-changing — requires confirm: true] REPLACES both exclusion lists. Call get_exclusions first and send the complete lists including everything being kept — a partial call silently drops the rest. The two are different: `fit` is about match quality, `reputation` is a veto that applies whatever the role. |
| list_resumes | reads | [free] Master resume versions and every tailored artifact produced so far, with the job each belongs to. Use it to tell the owner what already exists before spending tailor quota producing it again. |
| list_operations | reads | [free] Everything queued or recently finished — tailoring, prep packets, scoring — with status and any failure reason. Check here before starting metered work: what the user asked for may already be running. |
| get_tailored_document | reads | [free] READ a tailored resume, cover letter or prep packet as text. list_resumes gives you the artifact ids. This is what makes a draft reviewable: without it you can hand the owner a download link but cannot see what was produced, so you can neither critique it nor help them check it. ALWAYS read the draft before telling anyone it is ready — and read the gap list from get_operation alongside it. The guards stop the draft inventing figures; they cannot stop it being badly aimed, or carrying a credential from another industry onto this application. |
| get_master_resume | reads | [free] The parsed master resume: name, headline, contact and every section, as stored. This is the record tailoring mirrors — sections come out in this order, under these titles — so read it to understand why a draft is shaped the way it is, and to see what the record does NOT contain before promising it can. |
| mark_exemplar | confirm | [free, state-changing — requires confirm: true] PIN a master resume version for the tailoring studio, or unpin it: a fresh studio session starts from the newest pinned version instead of the newest upload. It does NOT teach tailoring a style (that is a sent final marked as an exemplar, in the app’s Drafts). Warn the owner when the pinned version is older than their newest master — the studio keeps reading the old one. |
| delete_tailored_document | confirm | [free, state-changing — requires confirm: true] Delete a tailored artifact. The posting, its score and its history are untouched — only the generated document goes. Use it to clear a draft the owner rejected so the next one is unambiguous. |
| get_usage | reads | [free] What has this cost me? Cycle usage vs plan quotas + estimated spend. |
| get_shortlist | reads | [free] TODAY'S SHORT LIST — the jobs worth the owner's time today, best first. Start every daily check-in here. Built each morning from new scored matches that clear the owner's bar (the same bar Matches uses), held stable for the day, and returned LIVE: each item carries its current status, score and written rationale, its stage if being pursued, any tailored documents, `appUrl` (the job in Jobably) and `reviewUrl` (where a draft is reviewed and downloaded). `carried: true` marks a match from an earlier list the owner has not acted on. `criteria.awaitingScore` counts recent matches not scored yet — they cannot make the list until they are, so an empty list with a non-zero awaitingScore means "scoring in progress", not "nothing fits". Pass `day` (YYYY-MM-DD) to read a past list. |
| regenerate_shortlist | confirm | [free, state-changing — requires confirm: true] Rebuild TODAY'S short list from the current matches — after the owner changed their floor or exclusions, or new matches were scored since this morning. Replaces the list everyone sees today. |
| list_applications | reads | [free] Everything the owner has applied to, newest first: status, date applied, whether a follow-up is due, the documents (including the final they sent), `appUrl` and `reviewUrl`. Record a new application with move_card (toStatus "applied") for a tracked job, or declare_applied for one found elsewhere. |
| show_tailored_resume | reads | [free] Show what the tailored resume for a job LOOKS like: the newest draft as text, its version, every other document for the job (cover letter, prep packet, the final the owner sent), and `reviewUrl` — where the owner reviews, finalizes and downloads it. Present the text to the owner; link reviewUrl for the formatted document. If no draft exists yet, says so (tailor_resume or the studio tools make one). |
| query_jobs | reads | [free] The flexible read for building the owner a table, report or list: any mix of statuses, a score range, found within N days, applied within N days, one search, one list, a company or a title/company text match, sorted by score, newest found or newest applied. Light columns (title, company, location, status, score, rationale, dates, appUrl) — use get_job for a full posting. |
| get_insights | reads | [free] The numbers for a report or dashboard: jobs by status, the score histogram, found and applied per week (12 weeks), the funnel from seen to closed, hit rate by search, median days from found to applied, open applications by age, and which agents acted on the account in the last 30 days. |
| get_activity | reads | [free] The activity record: who — the owner in the app, a personal access token, or a connected agent like you — did what, newest first, with the tool, the target and the outcome. Every change to the account is recorded before it is made. Filter by `via` (session | pat | oauth) or `client` (an agent or token name). Page with `before` set to the previous page’s nextBefore. |
| list_lists | reads | [free] The owner’s named job lists ("Dream companies", "Apply this week") with item counts. Lists are where an agent keeps a working set for the owner; they appear in the app and can be embedded in a report. |
| create_list | acts | [free, state-changing] Create a named list of jobs for the owner. Add jobs with add_to_list. Name it the way the owner would. |
| get_list | reads | [free] One list with its jobs: title, company, status, score, note, appUrl. |
| update_list | acts | [free, state-changing] Rename a list or change its description. |
| delete_list | confirm | [free, state-changing — requires confirm: true] Delete a list. The jobs on it are untouched — only the list goes. |
| add_to_list | acts | [free, state-changing] Add jobs to a list, optionally with a note (why they are there). Adding a job already on the list just updates its note. |
| remove_from_list | acts | [free, state-changing] Take one job off a list. The job itself is untouched. |
| list_reports | reads | [free] Reports and dashboards saved to the owner’s account — by the owner or by an agent — with their widget types and `appUrl` (where the owner opens it in Jobably). |
| get_report | reads | [free] One saved report. With render (the default) every widget comes back with its LIVE data — the same numbers the owner sees when they open it. |
| save_report | acts | [free, state-changing] Save a report or dashboard to the owner’s account, where it stays LIVE: widgets are queries, not snapshots, so it is still true next week. Pass `reportId` to replace an existing one. Widget types: markdown {body} (your written analysis — headings, lists, tables, links); stats {} (insights); funnel {}; jobs {query: the query_jobs fields, limit ≤ 50}; list {listId}; shortlist {}; activity {via?, limit?}. Each takes an optional title. Up to 20 widgets. Returns `appUrl` — give it to the owner. |
| delete_report | confirm | [free, state-changing — requires confirm: true] Delete a saved report. |
| get_profile | reads | [free] The owner’s profile: the questionnaire their scoring rubric is built from (seniority floor, locations, arrangements, comp floor, industries, title keywords), notification preferences, and whether a master resume exists. Read it before set_questionnaire or set_preferences. Includes the interview answers and conditional rules set_questionnaire can merge. |
| set_questionnaire | confirm | [free, state-changing — requires confirm: true] Set what the owner wants — the questionnaire every posting is scored against. MERGES: send only the fields that change; everything else is kept (interview answers merge field by field, conditional rules by id). Scoring needs this AND a master resume. Ask the owner rather than guessing — a wrong floor hides good jobs. |
| set_preferences | confirm | [free, state-changing — requires confirm: true] Notification and display preferences. MERGES over the stored ones. matchAlertFrequency: instant | daily | off (emails when a match clears alertThreshold); digestFrequency: daily | weekly | off; matchesMinScore: one floor for every search on Matches and the short list (useSearchThresholds: true goes back to each search’s own threshold); resumeBulletBudget: the most experience bullets a tailored resume keeps (0 keeps every bullet; useDefaultBulletBudget: true goes back to Jobably’s default). |
| upload_master_resume | confirm | [free, state-changing — requires confirm: true] Upload the owner’s master resume — what every score and every tailored draft is built from. Send `text` (the resume as plain text or Markdown, exactly as written — never rewritten or summarized) or `fileBase64` + `filename` for a .docx or .pdf. A Word file keeps its formatting in tailored drafts; text does not, so prefer the file when the owner has one. Creates a new master version; earlier ones are kept. |
| get_started | reads | [free] START HERE on a new account, or whenever the owner says "set me up" / "find me jobs". Returns where the account stands (`status`: resume, profile, searches, first scan, matches, scored), the NEXT step in words (`next.step`, `next.say`), and — once a master resume is uploaded and until the account is set up — a `proposal` drawn from it: a profile (`questionnaire`) and a first search, every value copied from the resume with its source in `basis`, plus `ask`: the questions only the owner can answer (pay floor, remote/hybrid/on-site, industries). Show the proposal, ask those questions, fold the answers into it, then call apply_setup. Steps: upload_resume → upload_master_resume; apply_setup → apply_setup; first_scan / scoring → wait a few minutes and call this again; score_matches → score_new_matches; ready → get_shortlist. |
| apply_setup | confirm | [metered: recurring scans every cadence — requires confirm: true] Set the owner up in ONE call, after they approved the proposal from get_started: saves the profile (`questionnaire`, which builds the scoring rubric) and creates each search, and the first scan runs immediately. Matches arrive within minutes; on a new account they are scored automatically (`scoring: "automatic"`), otherwise call score_new_matches. Send the proposal back with the owner’s answers folded in — `questionnaire` is the WHOLE profile (seniorityFloor required), `searches` is a list of {name, query, filters, scoreThreshold, cadenceHours} exactly as the proposal shapes them (filters takes the create_search filter names, e.g. location, experienceLevel, remoteOnly). Every search is checked before anything is saved: one that could never match refuses the whole call, naming it. Needs a master resume (upload_master_resume). |
| score_new_matches | confirm | [metered: scores every unscored match against the rubric — requires confirm: true] Score the owner’s unscored matches now, newest first. Subscribers’ new matches are scored automatically and so are a new account’s first; use this when get_started says `score_matches`. One run per account: asking again while one runs returns that run. Poll it with get_operation; scores appear on list_matches as they land. |