--- name: peopleseek-jobs description: Searches PeopleSeek Talent, a free public job index, through its remote MCP server (https://jobs.peopleseek.ai/mcp) or REST API (https://jobs.peopleseek.ai/api/v1), no key or account. Finds jobs by keyword, occupation (ESCO/ISCO), industry (ISIC), country, region, city, work arrangement, remote eligibility, salary, employment type, seniority, language, company and recency, and resolves places, occupations, industries and countries. Use it whenever a user wants to find jobs or openings, remote jobs they can apply to from a given country, jobs in a country or city, or a job family or title (for example "find jobs", "remote jobs I can apply to from the Philippines", "software engineering jobs in Germany", "healthcare jobs in Canada", "senior marketing positions in Singapore"). Not for submitting applications (peopleseek-job-application) or pay and career comparisons (peopleseek-career-research). metadata: version: 1.1.0 --- # PeopleSeek Jobs PeopleSeek Talent is a public, free job index. It aggregates postings from employer job boards and public feeds whose terms allow it, normalises them to one vocabulary and exposes them over REST and MCP. It is **not** every job on the internet: it covers the sources listed by `GET /health` and the coverage page, nothing else. Say so when it matters. ## 1. Choose the interface | Situation | Use | |---|---| | An MCP client is available (Claude Code, Claude Desktop, Cursor, any MCP host) | The remote MCP server. Tools: `search_jobs`, `get_job`, `find_similar_jobs`, `list_occupations`, `search_occupations`, `list_industries`, `list_countries`, `search_locations`, `get_application_options`, `check_job_status`, `compare_compensation`. | | Only HTTP is available (curl, fetch, a script) | REST at `https://jobs.peopleseek.ai/api/v1`. Same parameters, snake_case, in the query string. | MCP tool arguments use the same snake_case names as the REST query parameters. Two differences: in MCP `countries` and `status` are arrays; in REST they are comma-separated. Limits: REST 120 requests/minute per IP, MCP 60 requests/minute per IP. Connection snippets and curl examples: [references/interfaces.md](references/interfaces.md). ## 2. Procedure ### Step 1 — Read the request into filters Extract, when stated: the place, the role or job family, the work arrangement, where the user will be when working, pay expectations, employment type, seniority, language, company, and how recent. Do not add filters the user did not imply. Full parameter table: [references/parameters.md](references/parameters.md). ### Step 2 — Resolve the place - A country name → its ISO 3166-1 alpha-2 code (`list_countries` / `GET /countries` returns every country with live job counts; use it when unsure of the code). - A city or region name → `search_locations` / `GET /locations/search?q=` and take the best `score`. Use `country` + `city` (or `region`) from the match. If the match is ambiguous (two cities with the same name in different countries), ask or pick the one the conversation implies, and say which you picked. ### Step 3 — Resolve the role - A specific title ("data engineer") → pass it as `q`. The engine searches titles, summaries and skills. - A job family or broad wording ("healthcare jobs", "nursing", "sales roles") → `search_occupations` / `GET /occupations/search?q=` first. Pick the match(es) with the highest `confidence`; use `occupation_id` for a precise group, or `occupation` (free text) to let the server resolve it and echo `occupationResolved`. - An industry ("jobs in banking") → `list_industries` and pass the ISIC code as `industry_id`. Industry is the employer's sector, not the role. ### Step 4 — Pick the eligibility parameter (this is where searches go wrong) | The user says | Parameters | |---|---| | "jobs in Germany" / "based in Berlin" | `country=DE` (+ `city=Berlin`). The job is located there. | | "in Germany or Austria" | `countries=DE,AT` (MCP: `["DE","AT"]`). | | "remote jobs I can apply to from the Philippines" | `work_arrangement=remote`, `eligible_country=PH`. Returns jobs whose eligibility is worldwide or lists PH. Jobs with unknown eligibility are excluded by default. | | "...and show me the ones that do not say" | add `include_unknown_eligibility=true` and label those results "eligibility not stated". | | "remote, from anywhere" / "worldwide remote" | `work_arrangement=remote`, `worldwide_eligible=true`. | | "remote jobs in the US" | ambiguous: `country=US` means the job is located in the US; `eligible_country=US` means a US-based applicant is eligible. Ask, or run the eligibility form and say so. | | "hybrid in Singapore" | `country=SG`, `work_arrangement=hybrid`. | A remote job is **never** worldwide unless the employer said so. `remoteEligibility` in a result is `worldwide`, `countries` (see `eligibleCountries`), `unknown` (labelled remote, countries not established) or `not_applicable` (not remote). ### Step 5 — Search Call `search_jobs` (MCP) or `GET /jobs` (REST). Start with `limit` 20 (max 100). Sort: `relevance` (default, needs `q` or `occupation` to mean much), `posted_desc` for "newest", `verified_desc` for "confirmed recently", `salary_desc` for "best paid" (disclosed salaries only). The response carries `jobs`, `total`, `totalCapped`, `nextCursor`, `applied` (the filters as the server understood them) and `occupationResolved` when an occupation was given. Trust `applied`, not your memory. ### Step 6 — Paginate When `nextCursor` is not null and the user wants more, repeat the same call with `cursor=` and the same filters. Never change filters between pages. Tell the user the `total` (say "at least" when `totalCapped` is true). ### Step 7 — Present For each job, in this order: title; company name; location (`primaryCity`, `primaryRegion`, `primaryCountry`, or `locations[].raw` when unresolved); arrangement and eligibility in words; salary **only when `salary.disclosed` is true** (`min`–`max` `currency` per `period`, or `salary.raw`), otherwise "salary not stated" and never an estimate; employment type and seniority when present; `postedAt` and `verification.lastVerifiedAt`; the source (`source.name`) and, when `source.attributionText` is present, that text linked to `source.attributionUrl`; and the canonical link (`canonicalUrl`). The attribution and the canonical link are required by the sources' terms: a job is never shown without them. The PeopleSeek page (`url`) may be linked in addition, never instead. Say "listed on PeopleSeek as active, last verified " rather than "open": the index reports what the source showed at `lastSeenAt`. Any status other than `active` must be stated plainly ("closed on ", "stale: not seen since "). ### Step 8 — Empty results Report which filters were applied (from `applied`), then widen one step at a time, in this order, and say what you changed: drop `city` → drop `region` → add neighbouring `countries` → `include_unknown_eligibility=true` (eligibility searches) → replace `occupation_id` with `q` → drop `seniority` / `employment_type` → widen `posted_since`. Never say "there are no such jobs": say "the PeopleSeek index has no active posting matching …; it covers the sources listed by its health endpoint and coverage page, not every employer". ## 3. Rules that never bend - No estimates: salary, closing date, eligibility and location are shown as the source stated them or as "not stated". `null` means unknown, never "no". - Show source attribution and the canonical link with every job. - `remoteEligibility: unknown` is not "worldwide". Say "eligibility not stated". - Do not claim coverage the index does not have, and do not describe PeopleSeek as the employer or as acting for one. - Do not apply, draft applications or promise outcomes here; hand off to `peopleseek-job-application`. - Do not invent endpoints, tools or parameters beyond those in [references/parameters.md](references/parameters.md). ## 4. Worked examples [references/examples.md](references/examples.md) shows the exact MCP and REST calls and illustrative responses for: "remote software engineering jobs I can apply to from the Philippines", "healthcare jobs in Canada", "senior marketing positions in Singapore", "software engineering jobs in Germany", pagination, and a job detail with similar jobs. Field-by-field meanings: [references/response-fields.md](references/response-fields.md).