searchnapply

Search job postings

job_postings_search

Read-onlyIdempotent

Purpose: Find job postings that fit the user's role, location and fields, with a short summary per posting; left unset, the first twenty results come back. A lowest or highest yearly amount keeps a posting by what it itself published, and a seniority limit keeps a posting at its own posted level. When: The user describes work they want; gather a role and a location first. Cost: About 170 tokens per posting and 3020 for 20 postings.

Input Schema

Name	Required	Description
`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 when one fits (resolvedRole.display names it) and otherwise 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
`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.

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 27, 2026

TDQS

A4/5.0

Behavior4/5

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

With readOnlyHint and openWorldHint already declared, the description adds useful behavioral context: default first twenty results and token cost per posting. It does not cover auth or rate limits, but it goes meaningfully beyond annotations and schema defaults.

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?

The description is front-loaded and cleanly structured into Purpose, When, and Cost. Every sentence provides useful information without repeating the schema or annotations unnecessarily.

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?

For a 17-parameter search tool with full schema coverage, output schema, and annotations, the description covers purpose, trigger conditions, defaults, token cost, and key filter semantics well. A minor gap is that it does not name the full-description or field-exploration siblings when explaining the short summary and field options.

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 coverage is 100%, so the schema already documents all 17 parameters in detail. The description adds only a little semantic nuance around salary and seniority filtering, leaving most parameter meaning to the schema as intended.

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?

The description states a specific verb and resource: find job postings matching role, location, and fields, returning a short summary per posting. It is clear what the tool does, but it does not explicitly distinguish itself from siblings such as job_postings_search_fields or job_postings_get_full_description.

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?

It gives clear usage context: use when the user describes work they want, and gather a role and location first. It does not state when not to use it or name alternatives, but the triggering scenario is explicit.

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

All searchnapply tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?