Search job postings
job_postings_searchPurpose: Find job postings that fit the user's role, location and fields, with a short summary per posting. When: The user describes work they want; gather role and location first; in a chat app show results with job_postings_search_widget_render, unasked, and in a terminal as text. Cost: About 170 tokens per posting and 3020 for 20 postings.
Example tool call
This call uses example arguments supplied in the tool’s input schema.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"pageSize": 20,
"locations": [
"Austin, TX"
],
"titleText": "QA engineer",
"department": "software-it",
"experience": {
"min": "Mid level"
}
},
"name": "job_postings_search"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | The 1-based page number. | |
| sortBy | No | Result order; job_postings_search_fields explains each value. | |
| keywords | No | Words that must appear in the posting's text. | |
| pageSize | No | Postings per page, 1 to 50. | |
| companies | No | Company names; a posting from any of them is kept. | |
| locations | No | Location names in plain words, each read as the closest known location, so check resolvedLocations for what was actually searched. | |
| salaryMax | No | Highest yearly salary to keep, in US dollars after the same conversion. | |
| salaryMin | No | Lowest yearly salary to keep, in US dollars after each posting's published salary is converted. | |
| titleText | No | Words of the job title, matched to one of searchnapply's known roles (resolvedRole.display names it), else matched against posting titles. | |
| datePosted | No | How recently the posting was published; leave it out for any date. | |
| department | No | One department slug, to narrow a title that spans departments; call job_postings_search_fields for what each one holds. | |
| experience | No | Experience level to keep, as exactly one of exact or min. | |
| includeFamily | No | Also return postings from the resolved role's wider family; false, the default, keeps the exact role only. | |
| locationTypes | No | Workplace types to keep. | |
| employmentType | No | Employment type to keep. | |
| excludeKeywords | No | Words that must not appear in the title or the text, 1 to 10 words. | |
| includeNoSalary | No | Keep postings that publish no salary; true by default. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| hint | No | What to do next when the result needs a decision or a retry. | |
| page | Yes | The 1-based page returned. | |
| facets | No | How the matches split by department; absent on a narrowed or empty search. | |
| pageSize | Yes | How many postings a page holds. | |
| postings | Yes | The matching postings, one summary each. | |
| titleNote | No | Present when no role matched: the title words were matched against posting titles. | |
| totalCount | Yes | How many postings match in total. | |
| totalPages | Yes | How many pages the matches fill. | |
| familyLabel | No | The name of the role's wider family. | |
| familyTotal | No | How many more postings the role's wider family holds; present when the exact result is short. | |
| resolvedRole | No | The role the title words were read as; absent when no role matched. | |
| resolvedLocations | No | The locations that were searched, as resolved from the location names given. | |
| totalCountIsCapped | Yes | True when the count stopped at 1,000 and more postings match. | |
| unrecognizedLocations | No | The location names that matched no known location and were left out. |