JobsPipe

search_jobs

Read-only

Search live, normalized job postings across 30+ sources by title, skill/tech, country, remote, seniority, employment type and recency. Returns guidance for calling the authenticated REST API that runs the query.

Input Schema

TableJSON Schema

Name	Required	Description
`limit`	No	Maximum rows to return.
`remote`	No	Only remote roles when true.
`region_or`	No	US states and Canadian provinces as ISO 3166-2 codes, e.g. US-NY, CA-ON. Matches every spelling a job board publishes, so CA-ON finds both ON and Ontario. More precise than job_location_or for a state or province.
`skills_or`	No	Match jobs tagged with any of these skill slugs, e.g. python, kubernetes.
`benefits_or`	No	Match jobs advertising any of these benefit slugs, e.g. 401k, health insurance. Coverage is partial.
`job_title_or`	Yes	Match any of these job titles.
`metro_code_or`	No	Match any of these US CBSA metro codes, e.g. 35620 for New York. Non-US jobs never match.
`description_or`	No	Match any of these skills or technologies in the posting.
`min_salary_usd`	No	Only jobs whose posted salary reaches this annual USD amount. Jobs without a posted salary never match; estimated salaries are not consulted.
`job_location_or`	No	Match any of these cities or regions, e.g. Seattle, WA.
`max_ghost_score`	No	Exclude jobs whose ghost-likelihood score (0-100) exceeds this. Unscored jobs always pass.
`esco_skill_id_or`	No	Match jobs tagged with any of these ESCO skill concept IDs (exact match).
`isic_division_or`	No	ISIC Rev.4 employer industry divisions (2-digit, e.g. 62).
`job_seniority_or`	No	Match any of these seniority levels.
`employment_type_or`	No	Match any of these employment types.
`occupation_code_or`	No	ISCO-08 occupation codes; 4-digit exact, 1-3 digit as hierarchy prefix.
`has_recruiter_email`	No	true for only jobs with a recruiter contact email parsed from the posting, false for only jobs without one.
`job_country_code_or`	No	Match any of these ISO 3166-1 alpha-2 country codes.
`max_applicant_count`	No	Only jobs with at most this many applicants. Counts exist only where the source exposes them (LinkedIn), so this also drops every job without a count.
`visa_sponsorship_or`	No	Match any of these visa stances parsed from the posting text: offers, no, citizenship_required. Jobs that say nothing never match.
`work_arrangement_or`	No	Match any of remote, hybrid or onsite. Finer than remote, which answers false for hybrid and onsite alike. Jobs whose arrangement is unknown never match, and coverage is still backfilling, so this returns far fewer results than expected today; remote is the reliable filter for now.
`posted_at_max_age_days`	No	Only postings published within this many days.

TDQS

A3.7/5.0

Behavior3/5

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

Annotations already mark the tool read-only and open-world; the description adds context that data is live and normalized and that the output is 'guidance for calling the authenticated REST API.' However, it does not disclose pagination, rate limits, or the exact shape of the returned guidance, and the second sentence is underspecified.

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?

Two sentences with the primary capability front-loaded. The first sentence is dense but efficient; the second is vague ('returns guidance') yet short. Nearly every word earns its place.

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

Completeness2/5

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

With 22 parameters and no output schema, the description should explain return behavior more concretely. Saying it 'returns guidance for calling the authenticated REST API' is too vague about output format, pagination, limits, or result fields, leaving an agent unsure what to do with the tool's response.

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?

Input schema coverage is 100%, with every parameter already described, so the baseline is 3. The description's filter list (title, skill/tech, country, remote, seniority, employment type, recency) loosely echoes the schema but adds no parameter-specific nuance beyond it.

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 description opens with a specific action and resource: 'Search live, normalized job postings across 30+ sources,' and lists the main filter dimensions. This distinguishes it from sibling search_upwork_jobs by scope. The only slight wrinkle is the 'Returns guidance...' clause, but the primary purpose is unambiguous.

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?

The phrase 'across 30+ sources' sets clear context that this is a broad, multi-source job search rather than an Upwork-specific lookup. It does not explicitly name alternatives or give when-not-to-use conditions, so it falls short of the strongest guidance.

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

All JobsPipe tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4/5.0

Disambiguation4/5

Most tools are clearly distinct: listing sources and pricing plans are not easily confused with searching jobs. The only overlap is between search_jobs and search_upwork_jobs, since Upwork is presumably one of the 30+ sources, but the Upwork-specific tool provides unique budget and client signals that differentiate it.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case: list_job_sources, list_pricing_plans, search_jobs, search_upwork_jobs. The naming makes the action and target resource predictable across the entire set.

Tool Count5/5

Four tools is a tightly scoped set for a job-aggregation server, covering source discovery, plan information, general search, and specialized Upwork search. No tool feels redundant or unnecessary, and the count is neither thin nor bloated.

Completeness4/5

The core read-only domain is covered: agents can list sources, view pricing plans, search across all sources, and search Upwork specifically. Minor gaps such as a dedicated job-detail fetcher or source-filtered search could be workoundable, but they do not break the primary workflow.

Resources

Need Help?