Skip to main content
Glama
Sign In
OpenHire — Real Job Postings, Ghost Jobs Scored

OpenHire — Real Job Postings, Ghost Jobs Scored

by gzchenhao
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Check watches

check_watches

Pull new job matches for saved watches since their last check, typically at the start of a session. First pulls return a baseline of all matching postings and advance each watch's marker.

Instructions

Pull matches that are new since this fingerprint's last check.

stdio has no server push, so clients pull: call this at the start of a session. Returns the new matches per watch and advances each watch's last-notified marker. A board watch (registered with board_url) is read live here: its entry carries new_matches (appeared on the board since the last pull), closed_since_last (gone from the board) and total_matching; a board that does not answer comes back as board_error and nothing is marked closed on its account.

The FIRST pull on a watch returns everything matching it, not an increment: nothing has been reported for that watch before. On that pull the postings are under baseline_postings with baseline_count, new_matches is empty and is_first_pull is true; the top-level new_matches counts only increments and baseline_count the baselines. Never present a baseline to the user as "postings that appeared since last time".

Rows are compact (title, company, location, pay, dates_in_words, check_before_apply, apply link and the protocol fields; see fields): a full first pull used to run to 68,000 characters and get cut off. search_jobs with the job_id or company gives the full row.

Each result also carries total_matching and truncated: a broad watch can match hundreds of postings and only the 100 best-ranked are returned. Tell the user when truncated is true; the rest is not re-reported later.

Start your answer with the summary sentence (top level and per watch): it already says whether this is the first-pull baseline or an increment, and how many.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "fingerprint": "<fingerprint>"
    },
    "name": "check_watches"
  }
}

Input Schema

NameRequiredDescriptionDefault
fingerprintYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.3.2

TDQS

A4.4/5.0
Behavior4/5

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

Adds a great deal beyond the annotations: it discloses that each call advances a last-notified marker, that the first pull returns a baseline rather than an increment, that rows are truncated at 100 of `total_matching`, and that truncated results are not re-reported later. One gap: it never states what `fingerprint` is or where the client obtains it, so the state-mutation trigger is only half-explained.

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?

Roughly 350 words, but front-loaded with the action and pull-vs-push rationale, and each paragraph covers a distinct concern (baseline semantics, row compactness, truncation, summary). The closing paragraph is framed as an instruction to the agent ('Start your answer with the `summary` sentence'), which is slightly out of place but still functional output guidance.

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 one-parameter tool with no output schema, the description covers the return shape (per-watch entries, `new_matches`, `closed_since_last`, `baseline_postings`, `truncated`, `summary`) and the non-obvious edge cases. An agent could call and correctly report this without further context.

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

Parameters3/5

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

Schema coverage is 0%, so the description must carry the single parameter, and it only implies meaning ('this fingerprint's last check') without saying whether the fingerprint is client-generated, server-issued, or stable across sessions. That is a meaningful but incomplete compensation for the empty schema.

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 scope: 'Pull matches that are new since this fingerprint's last check.' It also implicitly separates itself from read_board (live board state) and search_jobs (full rows), so an agent can pick it without opening a 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?

Gives an explicit call-site ('call this at the start of a session') and names the alternative for a different need ('search_jobs with the job_id or company gives the full row'). It even covers the failure path (board that does not answer returns `board_error`).

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

Deploy Server

Other Tools