Hiring Signals

Watch companies for new and closed roles

watch_new_roles

Best for: following companies over time, such as "watch Stripe and Ramp and tell me about new roles". Returns: a watch_key, then on later calls the roles opened and closed since the last call (up to 100 of each listed, all counted). The first call is a baseline: it records the open roles and reports none as new. Input tips: {"companies": ["greenhouse:airbnb", "lever:spotify"]} to start; {"watch_key": "hs_..."} to check, plus companies to add (at most 25). Not for: a one-off look at one company (use company_hiring_brief).

Input Schema

Name	Required	Description	Default
`companies`	No	Careers page URLs, "ats:slug" tokens or company names, such as ["greenhouse:airbnb", "https://jobs.lever.co/spotify"]. Added to the watch.
`watch_key`	No	The watch_key an earlier call returned. Leave it out to start a new watch.

Output Schema

Name	Required	Description
`note`	Yes
`as_of`	Yes	ISO 8601 time the data was published by its source or fetched from it. A cached answer keeps the time of its fetch.
`since`	No	When the watch was last read.
`boards`	Yes
`failed`	Yes
`source`	Yes	Who the data comes from, to cite and to check it against.
`baseline`	Yes	True on a watch's first read: every open role is recorded and none is reported as new. A company added later is recorded the same way on its first read.
`new_count`	Yes
`new_roles`	Yes
`watch_key`	Yes	Keep it: it is the only way to read this watch again. Calls with it return changes since the last call.
`open_roles`	Yes
`api_version`	Yes	Date of this answer's shape; it changes only when a field is removed or changes meaning.
`closed_count`	Yes
`closed_roles`	Yes
`untrusted_source`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 23, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations only say it is stateful and open-world; the description adds the crucial semantics that the first call is a baseline returning nothing as new, that subsequent calls show opened/closed roles since the last call, and that counts are complete even when only 100 per category are listed. That baseline behavior is exactly the kind of non-obvious trait an agent would otherwise get wrong.

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?

Four labeled blocks (Best for / Returns / Input tips / Not for) with the routing decision front-loaded and zero filler sentences. Every line carries either selection guidance or non-obvious 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 two-parameter, stateful watch tool with an output schema, the description covers the start-vs-continue lifecycle, limits, and the alternative tool. Nothing an agent needs in order to call it correctly on either the first or a subsequent call 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 schema already documents both fields; the description goes further by explaining that companies are additive to an existing watch when combined with a watch_key and by showing concrete token examples. The 25-company cap is already in the schema, so it is a modest add rather than pure new meaning.

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 ('watch companies for new and closed roles') and frames it as following companies over time. It explicitly names the sibling it is not for (company_hiring_brief), so an agent can choose without opening either schema.

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?

Provides an explicit 'Best for' condition with a worked example, an explicit 'Not for' exclusion routing to company_hiring_brief, and covers both the start-watch and check-watch flows. Nothing about when to select this tool is left to inference.

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

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