Reqbeat Hiring Signals

Search open roles

search_jobs

Read-onlyIdempotent

Flat, role-granular job search -- the individual open roles across companies matching function / geo (country) / since, one row per logical req (each with its own company_id + req_key), LinkedIn-excluded (ATS tenants plus public job boards and aggregators; each row's board names its source) + freshness-floored. since filters on first_seen, our first observation of the req (not the employer's posting date); each row's source_posted_at is the date the source itself published, null when it gave none. Keyset-paginated via the opaque cursor (a prior call's next_cursor). Use who_is_hiring_for for the company-granular reverse view. function is a function name (a prior result's function_name, like 'Software & IT') or a function id (its function); anything else, like 'engineering', is rejected with an explicit error that lists the names, rather than an empty result -- pass plain language as q instead, which searches the posting's own title, expanded semantically to nearby titles, and reports each row's relevance (0-1). exclude_employer_types (e.g. ['staffing']) drops roles whose posting is classified as that employer type -- 'direct', 'staffing', 'consultancy' or 'unknown'; unclassified roles are kept unless 'unknown' is listed. q is independent of function: pass both to search titles within one function. sort is 'relevance' (the default with a q) or 'recency'; omit both and the page keeps its stable default order. limit is bounded: an oversized page is rejected rather than truncated, so page through the full set with cursor instead of raising limit. No key yet? The call answers with a signup link instead of rows.

Input Schema

Name	Required	Description
`q`	No
`geo`	No
`sort`	No
`limit`	No
`since`	No
`cursor`	No
`function`	No
`source_type`	No
`plane_api_key`	No	Deprecated: pass the key in the `X-API-Key` header. Removed in 1.2.
`idempotency_key`	No
`exclude_agencies`	No
`exclude_employer_types`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 19, 2026

addedInput schema / properties / exclude_employer_types

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Exclude Employer Types"
+}

Changed1 schema field changedOct 9, 2026

changedInput schema / properties / plane_api_key / description

Previous value: -"Deprecated: pass the key in the `X-API-Key` header, or omit the header for demo mode. Removed in 1.2."New value: +"Deprecated: pass the key in the `X-API-Key` header. Removed in 1.2."

Changed2 schema fields changedOct 6, 2026

addedInput schema / properties / function

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Function"
+}

removedInput schema / properties / role

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "title": "Role"
-}

Changed2 schema fields changedOct 5, 2026

addedInput schema / properties / exclude_agencies

Added value: +{
+  "default": false,
+  "title": "Exclude Agencies",
+  "type": "boolean"
+}

addedInput schema / properties / source_type

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "ats_tenant",
+        "board"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Source Type"
+}

Changed1 schema field changedSep 10, 2026

addedInput schema / properties / plane_api_key / description

Added value: +"Deprecated: pass the key in the `X-API-Key` header, or omit the header for demo mode. Removed in 1.2."

Changed2 schema fields changedAug 27, 2026

addedInput schema / properties / q

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Q"
+}

addedInput schema / properties / sort

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Sort"
+}

First observedJul 28, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds substantial behavioral detail beyond them: LinkedIn exclusion, freshness flooring, that `since` filters first_seen rather than the employer's posting date, source_posted_at null semantics, opaque keyset pagination, oversized-limit rejection rather than truncation, and the signup-link response when no key is present.

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?

Long but front-loaded: the core purpose and scoping clause lead, followed by parameter-specific behavior. Nearly every sentence carries operational information, though the prose is dense and slightly hard to scan given the many parenthetical asides.

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

Completeness4/5

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

For a 12-parameter tool with no output schema and 8% schema coverage, the description is close to sufficient, covering filtering, exclusion, sorting, pagination, and error behavior. It is not fully complete because exclude_agencies, idempotency_key, and source_type are undocumented anywhere.

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 only 8%, so the description must carry the load, and it does for most parameters (q, geo, since, function, cursor, limit, sort, exclude_employer_types), including non-obvious ones like exclude_employer_types keeping unclassified rows unless 'unknown' is listed. Gaps remain: exclude_agencies and idempotency_key are never addressed, and source_type is left to its enum alone, which prevents a 5.

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 with unusual precision: 'Flat, role-granular job search' over 'individual open roles across companies matching function/geo/since, one row per logical req (each with its own company_id + req_key)'. It explicitly distinguishes itself from the sibling who_is_hiring_for as the 'company-granular reverse view', so an agent can route between them without opening schemas.

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?

Explicit routing guidance: use who_is_hiring_for for the company-granular reverse view, and pass `q` (plain language) or `function` depending on intent, with the failure mode ('anything else, like engineering, is rejected with an explicit error'). It also covers sort defaults, cursor paging versus raising limit, and the no-key fallback, which is exactly the when/when-not guidance expected.

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

All Reqbeat Hiring Signals 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.

Search open roles

Input Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources