Openings

Search jobs

search_jobs

Read-onlyIdempotent

Search jobs immediately from role, country, location and optional stated experience. No resume required. Newest first; automatically widens 7, 14, 30 days then all dates until 5 matches. For another page reuse the same filters and returned window.daysUsed as maxAgeDays, with pagination.nextOffset. Resume-based ranking is optional via recommend_jobs.

Input Schema

TableJSON Schema

Name	Required	Description
`limit`	No	How many jobs to return in this page
`query`	No	Words to match in job title or company
`offset`	No	Where the page starts. Use pagination.nextOffset from the previous result rather than counting by hand
`remote`	No	True for remote-only; false for non-remote-only
`country`	No	Two-letter country code for job eligibility, such as IN or DE
`location`	No	Case-insensitive location substring
`maxAgeDays`	No	Omit to widen 7/14/30/all until 5 matches. Explicit positive values exclude undated roles; 0 includes all dates.
`experienceYears`	No	Years of experience to compare with the posting's stated min/max range; not a qualification or fit verdict.
`includeUnknownExperience`	No	With experienceYears, also keep roles without a stated range, clearly unknown rather than matched.

Output Schema

TableJSON Schema

Name	Required	Description
`jobs`	Yes	Matches, newest first
`window`	Yes	The age window the results came from, and whether it had to widen. Say which window was used
`guidance`	No	How to present these results honestly; meant for the assistant, not the candidate
`pagination`	Yes	offset, limit, total and nextOffset. nextOffset is null on the last page

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedSep 22, 2026

addedInput schema / properties / limit / description

Added value: +"How many jobs to return in this page"

addedInput schema / properties / offset / description

Added value: +"Where the page starts. Use pagination.nextOffset from the previous result rather than counting by hand"

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "properties": {
+    "guidance": {
+      "description": "How to present these results honestly; meant for the assistant, not the candidate",
+      "type": "string"
+    },
+    "jobs": {
+      "description": "Matches, newest first",
+      "items": {
+        "additionalProperties": true,
+        "description": "One matching job",
+        "properties": {
+          "age": {
+            "description": "Bucketed posting age; undated means the board gave no date, not that the role is fresh",
+            "enum": [
+              "new",
+              "older",
+              "stale",
+              "undated"
+            ],
+            "type": "string"
+          },
+          "company": {
+            "type": "string"
+          },
+          "eligibleCountries": {
+            "description": "Two-letter codes the role is open to",
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "experience": {
+            "additionalProperties": true,
+            "description": "Years the posting itself states as { min, max }; null when it states none, absent when the description was not read",
+            "type": [
+              "object",
+              "null"
+            ]
+          },
+          "id": {
+            "description": "Stable id to pass to get_job, analyze_job_fit or optimize_resume",
+            "type": "string"
+          },
+          "location": {
+            "type": "string"
+          },
+          "postedDaysAgo": {
+            "type": "number"
+          },
+          "remote": {
+            "type": "boolean"
+          },
+          "title": {
+            "type": "string"
+          },
+          "updatedAt": {
+            "description": "When the board says the role was posted or last updated; absent when the board states none",
+            "type": "string"
+          },
+          "url": {
+            "description": "The employer's own posting, which is where an application is made",
+            "type": "string"
+          },
+          "workMode": {
+            "enum": [
+              "remote",
+              "hybrid",
+              "onsite",
+              "unknown"
+            ],
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "pagination": {
+      "additionalProperties": true,
+      "description": "offset, limit, total and nextOffset. nextOffset is null on the last page",
+      "type": "object"
+    },
+    "window": {
+      "additionalProperties": true,
+      "description": "The age window the results came from, and whether it had to widen. Say which window was used",
+      "type": "object"
+    }
+  },
+  "required": [
+    "jobs",
+    "window",
+    "pagination"
+  ],
+  "type": "object"
+}

First observedSep 22, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses rich behavioral traits: 'Newest first' ordering, the non-obvious auto-widening algorithm (7/14/30 days then all dates until 5 matches), and the pagination window semantics. The widening behavior is surprising and would mislead an agent without this disclosure.

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?

Five short sentences, each earning its place: purpose, differentiator, behavior, pagination, and sibling routing. The core purpose is front-loaded in the first sentence, and the whole description is compact (~65 words) despite covering a 9-parameter tool with complex behavior.

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 complex tool with 9 parameters, an output schema (so return values are already documented), and safety annotations, the description covers everything an agent needs: purpose, differentiation, ordering, widening behavior, and the full pagination flow. No critical operational detail is missing.

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 100%, so the baseline is 3. The description adds genuine cross-parameter meaning beyond individual schema entries: it connects the response's window.daysUsed to the maxAgeDays input parameter and links pagination.nextOffset to the offset parameter, which no single schema field description conveys.

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 jobs') plus the search dimensions (role, country, location, optional experience). It also differentiates from siblings: 'No resume required' and 'Resume-based ranking is optional via recommend_jobs' explicitly separate it from the resume-driven recommend_jobs tool, and 'immediately' separates it from preparation-oriented siblings like prepare_job_search.

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 usage context: use this for immediate search without a resume, and names the alternative (recommend_jobs) for resume-based ranking. It also provides concrete operational guidance for pagination: reuse filters with window.daysUsed as maxAgeDays and pagination.nextOffset, which tells the agent exactly how to continue paging.

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

All Openings 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.