FoundRole Jobs

Changes a tracked job's status or sub-status and returns only the updated record, without rendering a tracker widget. FoundRole widgets call it for the in-place status dropdown; conversation-driven status changes go through tracker_update_status, which renders the tracker UI. It takes the same input.

tracker_update_status_data

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.

tracker_update_status

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. 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. A processing status means the personalized feed is still being prepared; a later call returns the completed feed.

jobs_recommendations

Lists the authenticated user's job alerts and returns only the data, without rendering an alerts widget. FoundRole widgets call it to populate and refresh an already rendered panel in place; conversation-driven listing goes through job_alert_list, which renders the alerts UI. It takes the same input.

job_alert_list_data

Re-runs personalized recommendations against the caller's current FoundRole profile and returns the refreshed feed without rendering a recommendations widget. FoundRole widgets call it to refresh an already rendered panel in place; conversation-driven requests go through jobs_recommendations, which renders the recommendations UI.

jobs_recommendations_data

Re-runs a job search with the caller's current FoundRole profile and returns the refreshed results without rendering a search widget. FoundRole widgets call it to refresh an already rendered panel in place; conversation-driven searches go through jobs_search, which renders the search UI.

jobs_search_data

Lists the authenticated user's tracked jobs and returns only the data, without rendering a tracker widget. FoundRole widgets call it to load more rows and refresh an already rendered panel in place; conversation-driven listing goes through tracker_list, which renders the tracker UI. It takes the same input.

tracker_list_data

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.

tracker_remove

Removes a tracked job and returns only the result, without rendering a tracker widget. FoundRole widgets call it for the in-place Remove control; conversation-driven removals go through tracker_remove, which renders the tracker UI. It takes the same input.

tracker_remove_data

Saves a job from jobs_search results into the user's tracker by its job_id and returns only the saved tracked job, without rendering a tracker widget. FoundRole widgets call it for in-place Save buttons; conversation-driven saves go through tracker_add, which renders the tracker UI. Repeated saves return the existing tracked job.

tracker_save

Saves a job posting found outside FoundRole search into the user's tracker and returns only the saved tracked job, without rendering a tracker widget. FoundRole widgets call it for in-place Save buttons on analyzed external jobs; conversation-driven saves go through tracker_add_external, which renders the tracker UI. It takes the same input as tracker_add_external: `url`, `company_name`, `title_name`, `location_name`, and `description` are required, every structured fact field is optional, and repeated saves return the existing tracked job.

tracker_save_external

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.

tracker_add_external

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.

tracker_add

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. 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. Each response includes a system_instruction describing how to present the sources.

knowledge_search

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. 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, a query for the profile's target profession or an omitted query uses the same personalized feed as jobs_recommendations and the website. Alternative titles matching that same profile target return the same ranked feed: parallel calls for those title variants can repeat jobs in separate widgets. Each call represents a distinct search intent, rather than a spelling variant of the same requested role. A different or unrecognized profession uses general job search, preserving the explicit query and filters. An omitted location uses the profile location. Without a ready profile, search uses the general job listings. 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. 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; sort orders the results by relevance, newest, salary or personal match. The search enforces only constraints passed as parameters; a constraint left out of the call is not applied to the result set. 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 never returns hybrid jobs. A job that does not state the filtered attribute is left out while that filter is set. Fully remote work that can be done from the requested location is strict_remote, with confirmed_work_from to require a stated work-from area; one brand inside a company is hiring_brand next to company. Advanced filters (sort, min_match, h1b_sponsors_only, salary_floor, remote, strict_remote, confirmed_work_from, work_modes, benefits, bonuses_only, companies, exclude_companies; sort only when ordering by salary or match, companies only 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. Each response includes a system_instruction describing how to present the results for the current client.

jobs_search

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.

reminder_set

Sets or replaces a tracked job's reminder and returns only the result, without rendering a tracker widget. FoundRole widgets call it when saving a deadline from an inline card edit; conversation-driven reminders go through reminder_set, which renders the tracker UI. It takes the same input.

reminder_set_data

Subscribes the authenticated user to job alerts for a saved job search and returns only the job alert, without rendering an alerts widget. FoundRole widgets call it for the in-place "Get alerts for this search" bar and alert toggles; conversation-driven subscriptions go through job_alert_subscribe, which renders the alerts UI. It takes the same input: `job_search_id` (UUID or composite job id) plus optional `frequency` and `delivery`, and repeated calls update the existing alert.

job_alert_enable

Unsubscribes the authenticated user from job alerts for a saved job search and returns only a success confirmation, without rendering an alerts widget. FoundRole widgets call it for in-place alert toggles; conversation-driven unsubscribes go through job_alert_unsubscribe, which renders the alerts UI. It takes the same `job_search_id` input, the status flip is reversible with job_alert_enable, and repeated calls stay successful.

job_alert_disable

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. Idempotent: returns success even when the user was not subscribed or is already unsubscribed.

job_alert_unsubscribe

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. Idempotent: returns success even when the user has no active alerts.

job_alert_unsubscribe_all

Updates a tracked job's notes, deadline, or reminder and returns only the updated record, without rendering a tracker widget. FoundRole widgets call it when saving inline card edits; conversation-driven updates go through tracker_update, which renders the tracker UI. It takes the same input.

tracker_update_data

Updates details of a tracked job (notes, 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 - `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.

tracker_update