Skip to main content
Glama

Nectar Jobs

Job posting trends over time

job_trends
Read-onlyIdempotent

How a slice of the market has changed OVER TIME — use this for "is X growing/shrinking", "hiring trend", "more or fewer than last year". aggregate_jobs describes a slice as it stands today; this one shows its history.

Takes the same filters as aggregate_jobs, plus ``bucket`` ("day"/"week"/"month"),
``since_days`` (at most 730), and ``measure``. Returns a ``series``, oldest first, each period carrying
``postings`` (roles dated to it, duplicates collapsed) and ``still_open`` (how many are live
now — the rest have since closed).

``measure="posted"`` (default) uses the employer's stated date: the market signal, but
nullable, so check ``without_date`` — it counts roles the clock cannot place, and when it
rivals the series totals the trend describes a minority of the slice.

``measure="first_seen"`` uses when we first crawled the row. Complete, but it measures OUR
coverage: a backfill or a newly onboarded board appears as a spike of hundreds of thousands
that is not a hiring event. Use it to audit ingestion, not to infer demand.

Either way, periods before ``earliest`` are empty because we hold no data that far back, not
because hiring stopped — never report that as a decline.

CRITICAL for "posted": only compare periods at or after ``crawl_started``. Earlier ones are
left-censored — the first crawl could only capture roles still live when it ran, so anything
posted before that and already closed was never seen. Those buckets undercount severely (their
``still_open`` sits near 100%, the giveaway), and reading across the boundary turns the
crawler's start date into a fake hiring boom.

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": "job_trends"
  }
}

Input Schema

NameRequiredDescriptionDefault
queryNo
bucketNomonth
remoteNo
sourceNo
companyNo
countryNo
measureNoposted
categoryNo
locationNo
seniorityNo
salary_minNo
since_daysNo
employment_typeNo

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already declare this a safe, idempotent read, so the description's job is to add semantic behavior — and it does: series ordering (oldest first), per-period contents (postings, still_open), nullability of posted dates and how to detect it via without_date, empty periods before earliest, and the left-censoring trap before crawl_started with the still_open≈100% diagnostic. This is disclosure an agent could not obtain from schema or annotations.

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-loads the core distinction from aggregate_jobs, then parameters, then output shape, then the caveats — a sound order. It is long and slightly repetitive (the posted-date warning surfaces twice: nullable/without_date and left-censoring), though every section carries decision-relevant information rather than filler.

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?

For a 13-parameter analytical tool with subtle data-quality traps, the description supplies what is missing elsewhere: output shape (even though an output schema exists), default values, and the two failure modes (undated roles, pre-crawl left-censoring) that would otherwise produce wrong conclusions. Nothing an agent needs in order to call and interpret this tool 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% across 13 parameters, so the description must carry the load — and it covers the three parameters that actually change interpretation: bucket values, since_days cap of 730, and the measure enum with its default and what each value measures. Remaining filters are pointed at via "same filters as aggregate_jobs", so naming the parameter meanings still depends on the agent consulting that sibling schema, which holds it just below a perfect score.

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?

States a specific resource and scope — job posting history over time — and explicitly contrasts with the sibling aggregate_jobs ("describes a slice as it stands today; this one shows its history"), so an agent can pick between them without opening either schema. It also names concrete user intents it serves ("is X growing/shrinking", "hiring trend", "more or fewer than last year").

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 an explicit routing rule to aggregate_jobs for point-in-time questions and reserves this tool for trend questions. It further segments usage by measure: "posted" is for market signal, "first_seen" is explicitly "to audit ingestion, not to infer demand", which is a real when-not-to-use instruction.

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