Skip to main content
Glama
Sign In
freehire

freehire

by strelov1
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

facets

Read-only

List live filter values, vacancy counts, skills, and numeric ranges first to discover valid search parameters and avoid inventing filter values.

Instructions

List the market's filter vocabulary: every facet's live values with a vacancy count each, plus the skills list and numeric ranges. Call this FIRST to discover real values for search and market_fit — do not invent facet values. A filter key the API does not recognise is ignored rather than refused, so a result wrapped as {data, ignored} counted a broader market than the one asked for — retry with the suggested name before quoting any number from it. A VALUE it does not recognise comes back in ignored_values (e.g. {"skills": ["golangg"]}): it matched nothing, so fix the spelling from this list rather than reporting an empty market.

Input Schema

NameRequiredDescriptionDefault
cityNoCity slugs. ORs with region and country.
roleNoRole facet values, e.g. senior_backend.
visaNoOnly jobs offering visa sponsorship.
facetsNoAny other facet param as key→value(s), e.g. {"source": "greenhouse"}. Discover valid keys and values with the `facets` tool.
regionNoRegion 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.
remoteNoOnly remote jobs (sets work_mode=remote).
companyNoCompany slugs.
countryNoISO-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.
categoryNoRole categories: backend|frontend|fullstack|devops|ml_ai|qa|...
seniorityNoSeniority: intern|junior|middle|senior|staff|principal|lead|c_level.
salary_minNoMinimum salary (enrichment.salary_min).
english_levelNoEnglish level, e.g. a2, b1, b2, c1.
exclude_skillNoSkills 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_typeNoEmployment type, e.g. full_time, contract.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.8.0
    • 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 / 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."
  2. First observedv0.1.0

TDQS

A4.1/5.0
Behavior5/5

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

Goes well beyond readOnlyHint=true by disclosing the API's silent-failure semantics: unknown filter keys are ignored rather than refused, results come wrapped as {data, ignored}, and unknown values return in `ignored_values` (with a worked example). It also gives the corrective action for each case, which is exactly the operational context annotations cannot carry.

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

Conciseness5/5

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

Three sentences, each load-bearing: purpose first, then call-order guidance, then the two silent-failure modes with their remedies. No restatement of the name or filler.

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

Completeness4/5

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

With no output schema, the description does the work of describing the return payload (facet values with counts, skills list, numeric ranges, and the {data, ignored} / ignored_values wrappers). The one gap is the unexplained 14-parameter signature on what is nominally a read-only vocabulary listing, which an agent may find puzzling.

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

Parameters3/5

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

Schema description coverage is 100%, so the 14 filter parameters are already fully documented in the schema and the baseline is 3. The description adds only indirect value by pointing at where valid facet keys and values come from; it says nothing about the individual parameters or why a discovery tool accepts search filters at all.

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

Purpose4/5

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

States a specific verb and resource: 'List the market's filter vocabulary' with concrete contents (live facet values, vacancy counts, skills list, numeric ranges). It is clear what the tool returns, but it never distinguishes itself from the sibling `list_filter_values`, which reads as a near-duplicate — an agent has no textual basis for choosing between them.

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

Usage Guidelines4/5

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

Explicit sequencing guidance: 'Call this FIRST to discover real values for `search` and `market_fit` — do not invent facet values', naming both downstream consumers and the anti-pattern. No exclusion against the similar `list_filter_values` sibling, so the routing is strong but not complete.

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

Deploy Server

Other Tools