Roleset — job postings index

Search jobs

search_jobs

Search the index of open job postings. Use for a one-off question about the job market: who is hiring for a role, what is open in a city or country, which companies have remote positions. Returns a page of job records plus a meta.next_cursor to continue; each record has title, company, structured locations, remote flag, employment type, salary when the board publishes one, and an apply URL. Descriptions are omitted unless include_description is set, because they are large. To find what has changed since you last looked, use job_changes instead — do not poll this tool in a loop.

Input Schema

TableJSON Schema

Name	Required	Description
`q`	No	Free text over title and description.
`ats`	No	Restrict to one ATS platform.
`limit`	No
`title`	No	Match on the job title.
`cursor`	No	From a previous meta.next_cursor.
`remote`	No	Only remote, or only non-remote.
`company`	No	Company name, partial match.
`country`	No	ISO-3166 alpha-2, e.g. US, DE.
`location`	No	City or region.
`department`	No
`posted_after`	No	ISO-8601 timestamp.
`employment_type`	No	full_time \| part_time \| contract \| intern \| temporary \| volunteer
`listed_since_after`	No	ISO-8601. When the company last put the role on the market — it moves when a posting is reopened, so this is the filter for what is on the market now.
`include_description`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 8, 2026

addedInput schema / properties / listed_since_after

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "ISO-8601. When the company last put the role on the market — it moves when a posting is reopened, so this is the filter for what is on the market now.",
+  "title": "Listed Since After"
+}

First observedSep 7, 2026

TDQS

A4.9/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and does so well. It discloses pagination via meta.next_cursor, the record fields included, the fact that descriptions are omitted unless include_description is set, and that polling in a loop is inappropriate.

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 with purpose, then explains return shape, the one caveat about descriptions, and the sibling alternative. Every sentence earns its place and there is no redundant restating of the tool title.

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?

Given 14 parameters, no annotations, and an output schema, the description still gives the agent everything essential: when to call it, what results look like, how pagination works, the expensive-field caveat, and when to choose a different tool. The parameter details are largely covered by the input schema.

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

Parameters4/5

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

Schema coverage is 79%, so the schema handles most parameter meaning. The description adds real value by explaining the include_description trade-off ('descriptions are omitted because they are large'), which is not clear from the schema's bare boolean field description.

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 verb and resource: 'Search the index of open job postings.' It also frames the use case ('one-off question about the job market') and distinguishes itself from job_changes, so an agent can tell it apart from the closest sibling tool.

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?

Explicitly says when to use it: for one-off job market questions such as who is hiring, what is open in a city or country, and which companies have remote positions. It also names the alternative for change detection ('use job_changes instead') and warns against polling this tool in a loop.

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

All Roleset — job postings index 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?