Skip to main content
Glama

Nectar Jobs

Search jobs

search_jobs
Read-onlyIdempotent

Search live job postings: use when the user asks what jobs are open for a role, a place, a salary or a skill. Each job carries url, its page on Nectar Jobs, where the person applies.

Args:
    query: keyword or natural-language query. Words that name an occupation ("manager",
        "software engineer") are matched against the TITLE; other words match the whole
        document (title, company, description), so a generic word's ``total`` overcounts —
        to compare role-type volumes, use aggregate_jobs instead.
    location: city or country substring over the posting's location text (matches broadly:
        "New York" includes the whole state). For a whole country, prefer ``country``.
    remote: filter to remote (true) or on-site (false) roles.
    salary_min: only roles whose salary range reaches this amount (raw number — currencies
        are not converted, so only meaningful combined with a single-currency market).
    company: company name substring.
    source: restrict to one source/board; get_stats lists the live sources and their sizes.
    seniority: one of intern, junior, senior, staff, principal, manager, director.
    category: job function from the site taxonomy (Engineering, "Data & ML", Product, Design,
        Sales, Marketing, "Customer Support", Operations, "Finance & Accounting",
        "People & HR", Legal, "IT & Security", …) — aggregate_jobs reports the live values.
    country: 2-letter ISO code ("US", "IN") — matches the derived country, more precise than
        a ``location`` substring.
    employment_type: contract or hours — permanent, fixed_term, contract, freelance, temporary,
        casual, seasonal, internship, apprenticeship, graduate, working_student, volunteer,
        self_employed, full_time, part_time, job_share, shift, term_time. Contract basis and
        schedule are one filter; a posting carries one of each. Note that a posting which says
        nothing about its hours is recorded as ``full_time``, so that value is the least
        informative of the set.
    posted_since_days: only jobs posted within this many days.
    mode: "hybrid" (default, best), "semantic" (meaning-based), or "keyword" (exact).
    sort: "relevance" (default), "date" (newest first), or "salary" (highest first).
    page: 1-based page number, for paging past ``limit`` results.
    limit: max results per page (1-100).
Returns a dict with ``total``, a ``jobs`` list (duplicates collapsed) and ``attribution``;
when nothing matched, a ``hint`` names the filter most worth loosening.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "search_jobs"
  }
}

Input Schema

NameRequiredDescriptionDefault
modeNohybrid
pageNo
sortNorelevance
limitNo
queryNo
remoteNo
sourceNo
companyNo
countryNo
categoryNo
locationNo
seniorityNo
salary_minNo
employment_typeNo
posted_since_daysNo

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.7/5.0
Behavior4/5

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

Annotations already declare read-only, idempotent, closed-world behavior, and the description adds real context beyond them: duplicates are collapsed, total can overcount, a hint is returned on empty results, and mode/sort/page have documented defaults. The main thing missing is any note on result cost or performance characteristics of the three modes.

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 usage before a well-structured per-argument block, and nearly every line carries non-obvious information. A few restatements of schema defaults (mode hybrid, sort relevance) and the long employment_type enumeration add length without adding insight.

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?

A 15-parameter open-ended search tool with an output schema; the description documents every filter, the return shape (total, jobs, attribution, hint), and the routing to siblings for aggregation and source discovery. Nothing an agent needs to call it correctly is absent.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must carry all 15 parameters — and it does: it gives enum values for seniority, employment_type and category, explains substring vs derived-field matching for location vs country, warns that currencies aren't converted for salary_min, and flags full_time as an uninformative default. This is far beyond what the bare schema provides.

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?

Opens with a specific verb+resource ("Search live job postings") and immediately names the user intents it serves (role, place, salary, skill). It also distinguishes itself from aggregate_jobs, which the description explicitly routes volume-comparison queries to.

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?

Gives explicit when-to-use framing plus several when-to-use-something-else rules: aggregate_jobs for role-type volumes, get_stats to list live sources, country over location for whole-country searches, and a single-currency caveat for salary_min. Alternatives are named rather than inferred.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources