Skip to main content
Glama

Reqbeat Hiring Signals

by com.reqbeat
OverviewDiscussionsAdmin

Find companies hiring for a role

who_is_hiring_for
Read-onlyIdempotent

WHEN an agent needs to FIND the companies worth working -- the sourcing step, before it knows which companies exist. Reverse who's-hiring-for {title, geo} search: companies with active reqs matching q/geo/since, deduped by company, keyset-paginated via cursor. q is free text matched against the posting title, not an id; plurals and other inflections match, so "backend engineers" is the same search. geo is resolved to a stored country before matching; an unresolvable one is an explicit error, never a quietly partial page. limit is bounded -- page through the full set with cursor instead of raising it. Billed per company returned (~0.10 EUR each) -- an empty result bills nothing. q="backend engineer", geo="USA" -> the companies with matching active reqs, each with its pulse and its matched reqs. geo="Atlantis" -> an explicit unresolvable-country error rather than an empty page. No key yet? Pass plane_api_key as an empty string and the call answers with a signup link instead of rows; on the hosted HTTP endpoint the key it mints finishes this exact search. Already holding a company_id and only need a yes/no? Use is_hiring.

Input Schema

NameRequiredDescriptionDefault
qNo
geoNo
limitNo
sinceNo
cursorNo
source_typeNo
plane_api_keyNoDeprecated: pass the key in the `X-API-Key` header. Removed in 1.2.
idempotency_keyNo
exclude_agenciesNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • 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."
  2. Changed2 schema fields changed
    • addedInput schema / properties / q
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Q"
+}
    • removedInput schema / properties / role
      Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "title": "Role"
-}
  3. Changed2 schema fields changed
    • 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"
+}
  4. Changed1 schema field changed
    • 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."
  5. First observed

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds genuinely new operational context: billing per company returned (~0.10 EUR), empty results billed nothing, bounded `limit`, explicit geo-resolution errors rather than partial pages, and the no-key signup-link behavior. The remaining gap is that the deprecated `plane_api_key` guidance sits in the schema rather than here, and source_type/idempotency/exclude_agencies behavior is unmentioned.

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 the WHEN clause and dense with earning sentences, including two concrete input→output examples. It is long and slightly overpacked (billing, auth, deprecation, behavior all in one paragraph), but little is wasted.

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?

No output schema exists, yet the description describes the return shape ('the companies with matching active reqs, each with its pulse and its matched reqs'), the error case, the pagination contract, and the auth path. For a 9-param open-world tool this is essentially complete.

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 11%, so the description must carry the load and mostly does: it clarifies `q` is free-text matched against posting title with inflection matching, `geo` is resolved to a stored country before matching (with explicit failure), `limit` is bounded and `cursor` is the pagination mechanism, and `since` is referenced. It leaves `source_type`, `idempotency_key`, and `exclude_agencies` entirely unexplained, which keeps it below 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 ('find the companies hiring') and frames it precisely as the reverse of who's-hiring search, deduped by company with keyset pagination. The opening WHEN clause plus the example output makes it distinguishable from siblings like is_hiring and get_open_reqs.

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 positions this as the sourcing step 'before it knows which companies exist' and routes a different need (already holding a company_id, wanting yes/no) to `is_hiring`. The when-vs-alternative split is stated, not implied.

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 toolsInspect
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