FoundRole — AI Job Search & Application Tracker MCP for Claude & ChatGPT

Lists the authenticated user's job alerts across all subscription sources (regular, company page, MCP).

Input:

• status: Filter by status — one of pending, active, unsubscribed (optional, default: all statuses)

• limit: Number of results to return (default 20, max 50)

• offset: Number of results to skip (default 0)

Output: Returns the user's job alerts with pagination info and a summary of the underlying job search (query, location, company where available).

Subscribes the authenticated user to job alerts for a specific saved job search.

Input:

• job_search_id: The job search identifier to subscribe to (required). Accepts either the job search UUID or the composite job ID returned by jobs_search / jobs_details (format: "seo_id--job_search_id").

• delivery: digest, fast (optional). Fast email is not available on every account and needs enough new matches for the exact saved search. Unsupported fast selection returns a validation error and keeps the existing delivery mode.

• frequency: Alert frequency — one of daily, weekly, monthly (optional, defaults to "weekly")

Output: Returns the created or updated job alert with id, status, and frequency, beside the user's current job alerts in the same shape and order as the first page of job_alert_list. Idempotent: calling this tool for an already-subscribed search updates the existing alert without creating a duplicate. An existing active alert with the same query text, location, company and filters, and at least the same radius, is returned instead of a new one, with the requested frequency applied to it. A user keeps one alert per query and place. When they already have an active alert for the same query and place with other filters, radius or sort, this tool changes that alert to the new search instead of adding a second one: the returned jobAlert.id is the existing alert, jobSearchId is the new search, and message says the alert was changed.

Delivery: Digest alerts arrive together in one email, one section per query and place. Opted-in fast alerts are sent separately while the account has them: matches found overnight arrive in one morning email at the hour the user usually starts the day, and later matches follow at least 3 hours after the previous email, up to 3 emails per local day. A fast email carries only jobs found since the previous one, never a job already sent to the user, a role from the same employer sent in the last 30 days, or a job in the user's tracker. When the account no longer has fast alerts they return to the ordinary digest and retain the saved fast preference. Each section applies every filter and the sort of its saved search, the same way jobs_search does for that account. A job appears in the digest once, even when it matches several alerts, and no email is sent when there are no new matches. The digest follows the most frequent alert, and arrives less often when the user has not used FoundRole for a while.

Unsubscribes the authenticated user from job alerts for a specific job search.

Input:

• job_search_id: The job search identifier to unsubscribe from (required). Accepts either the job search UUID or the composite job ID returned by jobs_search / jobs_details (format: "seo_id--job_search_id").

Output: Confirms the alert has been unsubscribed, beside the user's current job alerts in the same shape and order as the first page of job_alert_list. Idempotent: returns success even when the user was not subscribed or is already unsubscribed.

Unsubscribes the authenticated user from ALL of their job alerts at once, across every subscription source (regular, company page, MCP).

Input:

• confirm: Must be true to execute. The call is rejected when omitted or not true — this guards against an unintended bulk unsubscribe.

Output: Confirms how many alerts were unsubscribed, beside the user's current job alerts in the same shape and order as the first page of job_alert_list. Idempotent: returns success even when the user has no active alerts.

Analyzes one job found outside FoundRole using the authenticated user's FoundRole profile and the same signals used for FoundRole jobs: resume match, missing skills, H-1B sponsorship history, E-Verify, ghost-job risk, posted compensation, and market salary estimates. Use tracker_add_external only when the user asks to save without analysis.

The input represents the direct posting URL and all job content already available in the conversation. The five text identity fields are required; every structured fact field is optional, with a fact the source does not state simply omitted (or null). The optional client_extraction object carries evidence-backed skills, technology, benefits, bonuses, seniority, industry, management, clearance, visa, and remote-scope labels when source excerpts for them exist. FoundRole validates the evidence, stores the client extraction separately, derives missing deterministic facts, and reports which values were provided, derived, accepted, rejected, or remain unknown.

The output includes comparisonRef; retain it exactly for a later jobs_compare call. The analysis is a decision aid, not a guarantee about sponsorship, legitimacy, compensation, or hiring outcome.

Compares 2 to 4 jobs side by side using the same FoundRole analysis fields: resume match, missing skills, H-1B and E-Verify signals, ghost-job risk, posted pay, and market salary estimates.

comparison_refs accepts exact FoundRole job IDs returned by jobs_search and exact external comparisonRef URLs returned by jobs_analyze_external. Analyze each outside job first; a bare URL that has not been analyzed cannot be compared because FoundRole does not have its posting facts. Preserve every reference exactly, keep the user's requested order, and do not send duplicates.

Fetches full details for one job by the id returned from jobs_search — the deeper view behind a search result.

Input:

• job_id: The exact ID string from the id field of a jobs_search result.

• result_item_id: The matching occurrence ID from that result's resultItemId field, when available.

Output: Complete job details: description, skills, benefits, requirements, salary benchmark, resume match, H-1B and E-Verify signals, job-trust analysis, and application link. A posting that passed the fully-remote check carries remoteCheck: the posting lines that make the role remote and where the employee may work from, or an unknown scope when the posting does not say. repostHistory appears only when earlier copies of the posting closed one after another before this one opened: the date FoundRole first saw it, how many times it was reposted under a new link (0 when only the same link came back), and the same fact as one sentence. Its absence does not mean the posting is new. It is a fact about the posting, not part of the job-trust grade. Personalized and extended insight fields follow the authenticated user's current entitlements.

The pay estimate, the real-or-ghost grade, the remote check and the visa records are FoundRole's own figures: each carries source, basis (what it is computed from) and methodologyUrl, the FoundRole page that explains how it is computed. knowledge_search returns the same explanation. A false h1bSponsor or eVerify means no record was found in those files, not that the employer does not sponsor; a job whose employer FoundRole could not identify carries no visa fields.

Returns the authenticated user's personalized job recommendations built from their resume, skills, target roles, and preferred location. Results are ranked by fit, may include related roles, and carry the same salary, match, H-1B, and job-trust insight payload used by job search, with those FoundRole figures attributed once per response in figureSources (source, basis per kind of figure and methodologyUrl); a false h1bSponsor or eVerify means no record was found, not that the employer does not sponsor. The search filters and sort parameters apply to this personalized feed too. One call returns one answer: there is no next page, and the response links to the same feed on the FoundRole website. An explicit query for a different or unrecognized profession uses the same general job search as jobs_search, preserving the query and filters instead of substituting the profile's target roles. Without a location the feed covers the place saved on the account. It covers that place's whole country instead when the country holds more jobs of the account's role than the place does, or when the role has no job in the place or the country and few jobs of any kind are posted near the place; the latter shows related roles. The response names the place the feed shows as searchedPlace. A named location is never widened. coverage carries the counts of the role's jobs near the account's place and posted in its country. Its remoteOpenToCountry counts the role's jobs the feed holds with no posting near the place, whether remote, country-wide or regional, so that count does not mean they are remote.

A processing status means the personalized feed is still being prepared; a later call returns the completed feed.

Searches a database for real-time job listings matching the user's criteria.

The query is the full job title or role: "Ruby Developer" rather than a bare keyword like "Ruby", which is too broad and matches unrelated fields. roles_lookup turns words that name no exact role into FoundRole roles with their job counts. Results may be filtered by location, company, and how recently a job was posted.

Each result carries an id and resultItemId; jobs_details takes that id with the corresponding result_item_id and returns the job's full description, requirements, and benefits. One call returns one answer: there is no next page, and the response links to the same search on the FoundRole website for the rest of the list.

With a ready profile, an omitted query uses the same personalized feed as jobs_recommendations and the website; a query is a general job search that preserves the explicit query and filters. An account's saved role is reported in every response as savedRole; an omitted query or the saved role's title searches exactly that role, and any other query leaves the saved role unchanged. A search without a location runs in the place saved on the account, widened to its country when few jobs are posted near that city; an account with no saved place searches where the user is now when the client reports it, otherwise the default country. Such a response names the place searched as searchedPlace. A response for a request that names no exact role can carry a guide question the widget shows to the user. Job details include FoundRole salary benchmarks, H-1B sponsorship signals, E-Verify status, and job-trust analysis; list-level employer signals follow the user's current entitlements. Pay estimates, real-or-ghost grades and visa records are FoundRole figures, attributed once per response in figureSources: source (FoundRole), methodologyUrl (the FoundRole page that explains how they are computed) and, for each kind of figure the listed jobs carry (estimatedSalary, ghostScore, and visaRecords for h1bSponsor, eVerify and h1bPetitions), its basis (what it is computed from) and section link; knowledge_search returns the same explanation. A pay estimate's posting count is that job's estimatedSalary.sampleSize, and estimatedSalary.basedOn names the postings it was built from (the same role in the same area, or a wider match when that area has too few). A false h1bSponsor or eVerify means no record was found in those files, not that the employer does not sponsor; a job without them carries no visa claim.

Constraints in the user's request — remote-only work, H1B sponsorship, a minimum salary, a minimum match grade — are the search parameters remote, h1b_sponsors_only, salary_floor, and min_match. The search enforces only constraints passed as parameters; a constraint left out of the call is not applied to the result set.

Every request is ordered by relevance to the query. The sort parameter (score, posted_at, match, salary) replaces that order: posted_at orders by posting date and does not rank by fit to the query, salary orders by pay and match by personal fit. posted_days_ago is a posting window: it removes every job older than the window from the answer, so a narrow window can leave the answer empty.

Job type, work mode, required education, experience level, benefits, bonuses, employers to include or exclude, and the search radius are the parameters employment_types, work_modes, education, experience_levels, benefits, bonuses_only, companies, exclude_companies and radius. Remote and hybrid are independent work modes: a remote search returns hybrid jobs only as marked additions to a short answer. A job that does not state the filtered attribute is left out while that filter is set. One brand inside a company is hiring_brand next to company.

A company name that several employers share covers all of them, and the response names each with its domain; an employer's domain in place of a name (company, companies or exclude_companies) means that employer alone.

When fewer than 4 jobs match, the answer is widened and each added job carries widened, the condition that was widened (window, radius, hybrid). A search limited by posted_days_ago adds jobs from the next longer window, up to no window; a city search that matched nothing adds jobs within 100 miles; a remote search adds hybrid jobs in its place. Jobs that met the request as asked come first, and widening states how many there were and what each step added. Experience level, job type, pay floor, employer, visa sponsorship and every other filter are never widened.

Advanced filters (sort, min_match, h1b_sponsors_only, salary_floor, remote, work_modes, benefits, bonuses_only, companies, exclude_companies; sort when it orders by salary or match, companies when it names more than one employer) apply for every account. One answer lists the first matching jobs and states how many further jobs match.

Searches FoundRole's published content by semantic similarity and returns the most relevant sources for a job-search question: career-guidance blog articles plus FoundRole site pages that describe the product's features (job tracker, H1B salary data, AI job search) and industry/sector career landings. Each article carries a title, url, summary, a content excerpt, publication date, and tags; each page carries a title, url, description, and its FAQ entries — enough material to answer the question and link the source.

Two optional facets add further result groups: company returns FoundRole's employer profile pages matching that company name; location returns the market landing page for that city, state, or country — an analytical page about that labour market, not a list of openings. The facets describe what the user is asking about — a company mentioned only in passing does not need the company facet.

Every response to a question also carries methodology: FoundRole's own explanation of how its pay estimates, real-or-ghost grades, remote checks and visa sponsorship records are computed, with the url of the page that publishes it. It answers where a FoundRole figure comes from.

Returns empty groups when nothing is relevant rather than padding with off-topic content. Results are the closest matches to the given question, not an index of the site's full coverage; questions about overall topic coverage are answered by knowledge_topics, which lists the blog's categories and tags with article counts. It does not search job listings and reports no open-job counts — jobs_search covers live roles, including questions about openings for a particular job title.

Lists what FoundRole's published career-guidance blog covers: every category and the most-used tags, each with its published-article count and url, plus the total number of published articles. This is the factual source for questions about the blog's topics or overall coverage. It takes no parameters and reflects the live published corpus. It does not retrieve articles for a specific question; knowledge_search does that.

Replaces the roles saved on the user's FoundRole account with the one role the user chose. The previous roles are removed from the account, including a role taken from the user's resume. Recommendations then show the new role's newest jobs in the account's place, and later searches with no title search exactly that role. For an account with no role yet, profile_role_set saves one without removing anything.

Saves the one role the user said they are looking for on an account that has no role yet, creating its profile when it has none. Recommendations then show that role's newest jobs in the account's place, and later searches with no title search exactly that role. The FoundRole search panel calls it when the user picks a role there; a role the user names in the chat is saved the same way. It saves only a role the user chose, not a guess from their words. On an account that already has another role it changes nothing and names the saved role; profile_role_replace replaces it.

Deletes a reminder from a tracked job.

Input:

• tracked_job_id: The tracked job ID — trackedJobs[].id from tracker_list output, distinct from trackable.id and job.id (required)

Output: Returns the updated tracked job with reminderAt cleared.

Lists tracked jobs that have reminders set, ordered by reminder time (soonest first).

Input:

• limit: Number of results to return (default 20, max 50)

Output: Returns a list of tracked jobs with active reminders.

Sets a reminder for a tracked job. Sends a confirmation email with .ics calendar attachment.

Input:

• tracked_job_id: The tracked job ID — trackedJobs[].id from tracker_list output, distinct from trackable.id and job.id (required)

• remind_at: Reminder date/time in ISO 8601 format, e.g. "2025-03-15T10:00:00Z" (required, must be in the future)

Output: Returns the updated tracked job with reminderAt field.

Checks resume text for machine-readable sections, recognized skills, contact channels, a headline, and experience date ranges using FoundRole's deterministic parser.

Pass resume_text to check plain text supplied in the conversation. If resume_text is omitted, the tool reads the previously extracted text of the primary resume in the authenticated user's FoundRole account. It returns a readability band (strong, good, partial) and the single biggest loss. Depending on the account it also returns additional findings and the parsed facts (headline, years of experience, sections, contact channels, recognized skill count). Each finding includes a suggested fix. A saved report link is returned only when the account already has access to that report. This is FoundRole's text-readability assessment, not a test against a named ATS, a hiring prediction, or a file-layout check. Pasted text does not preserve the original PDF or DOCX layout.

The tool does not upload a file, create a saved resume or report, change the user's profile, submit an application, or fetch URLs found in the text. It may return a FoundRole website link; opening that link and uploading or editing a resume are separate user actions. Operational request records and diagnostics may retain tool inputs; this tool does not promise that submitted text is never stored.

Matches the user's own words for the work they want against FoundRole's role list and returns up to 5 roles with open jobs, each with its number of open jobs in the place's state or country, most jobs first, plus the role already saved on the account. It runs no job search and changes nothing on the account. jobs_search returns the jobs for a role.

Tracks a job from jobs_search results in the user's job tracker, identified by its job_id. For a job found elsewhere on the open web (with a URL but no jobs_search job_id), tracker_add_external is the right tool instead.

Fields:

• job_id: the job ID from jobs_search results (required)

• status: initial status (saved, applied, interviewing, offered, archived); defaults to "saved"

• sub_status: sub-status within the main status: saved: interested, researching_company, preparing_application, ready_to_apply; applied: application_submitted, followed_up; interviewing: interview_scheduled, phone_screen, technical, onsite, final_round, pending_feedback; offered: negotiating, considering, offer_received, accepted; archived: ghosted, rejected_by_company, withdrawn_by_candidate, not_interested, employed_by_this_company, employed_by_another_company

• notes: notes about the job

Returns the tracked job with its details. Repeated saves return the existing tracked job. A job that was previously removed from the tracker is restored with its earlier status and notes.

Saves a job posting found anywhere on the open web into the user's tracker. For jobs that came from jobs_search results, tracker_add (which takes a job_id) is the right tool instead. A job seen elsewhere in the conversation needs no prior jobs_search call — its URL and details from the conversation are sufficient input.

url, company_name, title_name, location_name, and description identify the posting and are the only required fields. Every structured fact field (salary, dates, employment type, education, experience) is optional: a fact the source does not state is simply omitted (or null), and FoundRole's own extractors derive missing salary, employment, work-arrangement, education, experience, skills, benefits, and bonuses from the description. A save never waits on facts the source did not provide. The optional client_extraction object carries evidence-backed skills, technology, benefits, bonuses, seniority, industry, management, clearance, visa, and remote-scope labels when source excerpts for them exist; FoundRole validates and stores those labels separately.

Fields:

• url: the job posting's direct URL (required; not a company homepage)

• company_name: company name (required)

• title_name: job title (required)

• location_name: location, e.g. "New York, NY" (required)

• description: the posting's description from the source result; a short summary is acceptable (required)

• salary_min_value / salary_max_value: salary range bounds (numbers)

• salary_value: a single salary figure when there is no range (number)

• posted_at: ISO 8601 posting date

• salary_currency: ISO 4217 currency code

• salary_type: one of year, month, week, day, hour

• employment_type: array of full_time, part_time, contractor, temporary, intern, volunteer, per_diem, other

• work_location_type: one of on_site, remote, hybrid

• education_requirements: array of no_requirements, high_school, associate_degree, bachelor_degree, professional_certificate, postgraduate_degree

• experience_months: minimum required experience in months (number)

• client_extraction: evidence-backed extraction object; fields without source evidence are omitted

• status: initial tracking status (saved, applied, interviewing, offered, archived); defaults to "saved"

• sub_status: sub-status within the main status: saved: interested, researching_company, preparing_application, ready_to_apply; applied: application_submitted, followed_up; interviewing: interview_scheduled, phone_screen, technical, onsite, final_round, pending_feedback; offered: negotiating, considering, offer_received, accepted; archived: ghosted, rejected_by_company, withdrawn_by_candidate, not_interested, employed_by_this_company, employed_by_another_company

• notes: notes about the job

Returns the tracked job. Repeated saves return the existing tracked job.

Lists the user's tracked jobs with optional filtering and pagination.

Input:

• status: Filter by status (saved, applied, interviewing, offered, archived)

• limit: Number of results per page (default 20, max 50)

• offset: Number of results to skip (default 0)

Output: Returns a list of tracked jobs grouped by status with pagination info. A tracked FoundRole job's job.estimatedSalary is FoundRole's pay estimate; the response attributes it once, in figureSources: source (FoundRole), methodologyUrl (the FoundRole page that explains how it is computed) and the estimate's basis, whose posting count is each job's estimatedSalary.sampleSize and whose match is each job's estimatedSalary.basedOn.

Each tracked job carries daysSinceApplied, the whole days since its applied date in the user's time zone. A job still at the applied status also carries followUpDay: the latest follow-up point it has reached (7, 14 and 21 days after applying), null before the first one. appliedDateUnknown is true for a job at the applied status with no stored applied date, unless the person said they do not remember it: FoundRole never fills that date in by itself, it comes from the person, and tracker_update stores it in applied_at or, when they do not remember it, in applied_date_declined. FoundRole never moves or archives a tracked job by itself.

Removes a job from the user's job tracker.

Input:

• tracked_job_id: The tracked job ID — trackedJobs[].id from tracker_list output, distinct from trackable.id and job.id (required)

Output: Confirms the job was removed from tracking.

Updates details of a tracked job (notes, applied date, deadline, salary, tags).

Input:

• tracked_job_id: The tracked job ID — trackedJobs[].id from tracker_list output, distinct from trackable.id and job.id (required)

• notes: Updated notes

• applied_at: The day the person applied, as they stated it: an ISO 8601 date or datetime, e.g. "2025-03-10" (a date without a time is read in the user's time zone; a future date is rejected; empty clears it). It is the value behind appliedDateUnknown in tracker_list output.

• applied_date_declined: True when the person said they do not remember when they applied; FoundRole then stops listing the application as having no applied date (appliedDateUnknown). False takes that back. Saving applied_at takes it back too.

• deadline: Deadline date (ISO 8601 format)

• salary_offered: Salary amount

• salary_offered_type: Salary type: year, month, week, day, hour

• tags: Comma-separated tags (e.g., "remote,startup,tech")

• reminder_at: Reminder date/time in ISO 8601 format, e.g. "2025-03-15T10:00:00Z" (must be in the future, or empty to clear)

Output: Returns the updated tracked job.

Updates the status of a tracked job.

Input:

• tracked_job_id: The tracked job ID — trackedJobs[].id from tracker_list output, distinct from trackable.id and job.id (required)

• status: New status: saved, applied, interviewing, offered, archived (required)

• sub_status: Sub-status within the main status, valid only for that status (optional): saved: interested, researching_company, preparing_application, ready_to_apply; applied: application_submitted, followed_up; interviewing: interview_scheduled, phone_screen, technical, onsite, final_round, pending_feedback; offered: negotiating, considering, offer_received, accepted; archived: ghosted, rejected_by_company, withdrawn_by_candidate, not_interested, employed_by_this_company, employed_by_another_company

Output: Returns the updated tracked job.