freehire

search

Read-only

Search open jobs by keyword and facet filters to retrieve full job descriptions, companies, locations, and total match counts for screening result sets without individual job lookups.

Instructions

Search open jobs by keyword with optional facet filters. Each result carries the job's FULL description as markdown alongside title, company, location and public_slug, plus the total match count — so you can screen a whole result set without calling job per hit. Use the returned slug with job, apply, save, etc. How to search well: a role has several names, so join two or three in one query with an uppercase OR, e.g. title:SRE OR title:"site reliability". Location, work mode, seniority and skills go in their filters, never in the query. If suspiciously few results come back, loosen one constraint at a time and say which. Present results as a table of title, company, location, posted date and link, naming the source. Two traps worth knowing. Geography (region/country/city) is ONE OR-group: passing region AND country widens rather than narrows, so drop the region to search a single country. And a filter param the API does not recognize is ignored rather than refused — the search still runs, just broader — so when a result carries an ignored list, its total answers a wider question than the one asked; retry with the suggested name before reporting the number. A value the API does not recognise (a misspelt skill, say) is reported in ignored_values and matches nothing — a total of 0 beside it is a typo, not an empty market: take the right value from list_filter_values and retry.

Input Schema

Name	Required	Description
`city`	No	City slugs. ORs with region and country.
`role`	No	Role facet values, e.g. senior_backend.
`visa`	No	Only jobs offering visa sponsorship.
`limit`	No	Max results to return. Each result includes a full job description, so prefer a modest value.
`query`	Yes	Free text over title, company, description and location. Empty string matches all. Operators: double quotes require every quoted word; -word excludes; uppercase OR between terms matches any alternative (at most 5), e.g. golang OR rust; title: at the start of an alternative matches the title only, e.g. title:"product owner" OR title:produktchef.
`facets`	No	Any other facet param as key→value(s), e.g. {"source": "greenhouse"}. Discover valid keys and values with the `facets` tool.
`offset`	No	Pagination offset.
`region`	No	Region codes: global\|ru\|cis\|central_asia\|eu\|us. WIDENS with country/city — region+country means 'in the region OR the country', not 'the country inside the region'. To search one country, pass country and OMIT region.
`remote`	No	Only remote jobs (sets work_mode=remote).
`skills`	No	Filter to jobs listing these skills (canonical slugs from the `facets` tool).
`company`	No	Company slugs.
`country`	No	ISO-3166 country codes, e.g. BR, US. Omit `region` when narrowing to a country — the two OR together, so region+country returns everything the region alone would.
`category`	No	Role categories: backend\|frontend\|fullstack\|devops\|ml_ai\|qa\|...
`seniority`	No	Seniority: intern\|junior\|middle\|senior\|staff\|principal\|lead\|c_level.
`salary_min`	No	Minimum salary (enrichment.salary_min).
`english_level`	No	English level, e.g. a2, b1, b2, c1.
`exclude_skill`	No	Skills to filter OUT, e.g. python — drops jobs TAGGED with any of them. Tags come from a curated dictionary read off the description, so this is a discovery filter, not a fit test: a mention the dictionary does not recognise leaves the job untagged and in the results, and a job whose real core is a stack the candidate lacks is not removed by excluding a different one. Any other facet excludes the same way through `facets`, e.g. {"company_type_exclude": "outstaff"}.
`employment_type`	No	Employment type, e.g. full_time, contract.

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedv0.8.0Oct 30, 2026

changedInput schema / properties / city / description

Previous value: -"City slugs."New value: +"City slugs. ORs with region and country."

changedInput schema / properties / country / description

Previous value: -"ISO-3166 country codes, e.g. BR, US."New value: +"ISO-3166 country codes, e.g. BR, US. Omit `region` when narrowing to a country — the two OR together, so region+country returns everything the region alone would."

addedInput schema / properties / exclude_skill

Added value: +{
+  "description": "Skills to filter OUT, e.g. python — drops jobs TAGGED with any of them. Tags come from a curated dictionary read off the description, so this is a discovery filter, not a fit test: a mention the dictionary does not recognise leaves the job untagged and in the results, and a job whose real core is a stack the candidate lacks is not removed by excluding a different one. Any other facet excludes the same way through `facets`, e.g. {\"company_type_exclude\": \"outstaff\"}.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedInput schema / properties / limit / description

Previous value: -"Max results to return."New value: +"Max results to return. Each result includes a full job description, so prefer a modest value."

changedInput schema / properties / query / description

Previous value: -"Keyword query, e.g. 'golang backend'. Empty string matches all."New value: +"Free text over title, company, description and location. Empty string matches all. Operators: double quotes require every quoted word; -word excludes; uppercase OR between terms matches any alternative (at most 5), e.g. golang OR rust; title: at the start of an alternative matches the title only, e.g. title:\"product owner\" OR title:produktchef."

changedInput schema / properties / region / description

Previous value: -"Region codes (OR within): global|ru|cis|central_asia|eu|us."New value: +"Region codes: global|ru|cis|central_asia|eu|us. WIDENS with country/city — region+country means 'in the region OR the country', not 'the country inside the region'. To search one country, pass country and OMIT region."

First observedv0.1.0Jul 11, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint, so the description carries the rest and does it well: it discloses the heavyweight result payload (full markdown description per hit), that unrecognized facet params are silently ignored, that `ignored`/`ignored_values` can make `total` answer a wider or empty question, and that geography facets OR rather than AND. These are exactly the traps that would cause a wrong answer.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and payload, then a clearly signposted 'How to search well' and 'Two traps' section. It is long for a description, and the region/country OR-group is explained both here and in the schema, but almost every sentence carries actionable guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 18-parameter tool with a nested `facets` object and no output schema, the description supplies the missing pieces: the shape of each result, the meaning of `total`, the `ignored`/`ignored_values` diagnostics, and how to present output. Nothing needed to call it correctly or interpret results is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and already documents most params, including the region/country widening caveat. The description still adds genuine guidance beyond the schema: query OR-operator practice with role synonyms, keeping location/work mode/seniority out of the query, and the ignored-param recovery loop. It loses a point only because the geography trap is partially restated from the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states a specific verb and resource ('Search open jobs by keyword with optional facet filters') and the follow-up names the payload shape (full description markdown, title, company, location, public_slug, total). It clearly distinguishes itself from `job` (per-hit lookup), `similar_jobs`, and `facets` (value discovery).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing: use the returned slug with `job`, `apply`, `save`; use `list_filter_values` to fix unrecognised values. It also states recovery strategy (loosen one constraint at a time and say which) and where filters belong versus the query string — no inference required.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools