Skip to main content
Glama
gzchenhao

OpenHire — Real Job Postings, Ghost Jobs Scored

by gzchenhao
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Watch a job intent

watch_intent

Save a standing job-search intent so new postings matching your skill, role, salary or location filters can be pulled later without searching again.

Instructions

Register a standing intent so new matches can be pulled later.

The caller supplies its OWN anonymous fingerprint (e.g. "#a3f9-k2p7-x8q1"; make it 12+ random characters, a four-character tag collides with strangers) — the client generates and owns it; the server stores but can never recover it, so persist it client-side and pass the identical one to check_watches. Only the fingerprint and non-PII filter keys are stored — never a name, email, phone or résumé. Accepted filter keys mirror search_jobs: skills (ANY-overlap), required_skills (ALL/AND — use this to keep sales / solutions-architect roles out), remote (bool), role_family (e.g. "engineering"), min_salary (int), company (one employer, resolved at registration), location (substring of the location text, alias-aware like search_jobs: 广州 also reaches 广东·天河区 rows, Beijing reaches 北京市, "remote" reaches 远程), title (list of title substrings, ANY-of, synonym-expanded for HR terms like search_jobs — the way to watch for recruiting or other roles no skill tag names). Any other key is REFUSED (ERR_UNKNOWN_FILTER) rather than silently dropped, and a role_family outside engineering | data | product | design | marketing | sales | ops | other is refused too (ERR_UNKNOWN_ROLE_FAMILY).

min_salary keeps rows with NO stated pay (they cannot be ruled out); it only drops rows whose stated pay is below the floor. Pay is stated mostly where law requires it (US postings on Greenhouse/Lever/Ashby), so a watch that needs a number will lean US.

Returns { watch_id, status, fingerprint, existing_watches, fingerprint_notice }. existing_watches > 0 means this fingerprint was already in use; if those watches are not yours, pick a longer random fingerprint.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
filtersYes
fingerprintYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.3.2

TDQS

A4.7/5.0
Behavior5/5

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

With annotations only declaring non-readOnly/non-idempotent/non-destructive, the description carries the rest and then some: privacy guarantees (server can never recover the fingerprint, no PII stored), hard refusals (ERR_UNKNOWN_FILTER for unknown keys, ERR_UNKNOWN_ROLE_FAMILY for invalid role_family), and the counterintuitive min_salary behavior of retaining rows with no stated pay.

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 core purpose, then organized by concern (privacy, filter keys, errors, return). It is long, but the length is largely forced by 0% schema coverage and two nested free-form filters; a few parenthetical examples (e.g. the fingerprint illustration) could be trimmed without loss.

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?

Although there is no output schema, the description enumerates the return fields (watch_id, status, fingerprint, existing_watches, fingerprint_notice) and explains how to act on existing_watches > 0. For a mutation tool with a free-form filter object and zero annotation detail, nothing an agent needs to call it correctly is missing.

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

Parameters5/5

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

Schema coverage is 0% and `filters` is a free-form object with additionalProperties, so the description must define semantics itself — and it does, documenting five accepted filter keys, their matching logic (ANY-overlap vs ALL/AND), alias-aware location matching, and enumerating legal role_family values. The fingerprint format requirement (12+ random characters) and its collision tag are also specified.

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 ('Register a standing intent so new matches can be pulled later') and immediately distinguishes itself from siblings by naming check_watches as the paired read tool. An agent can tell this apart from search_jobs (one-off) 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 Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Routing is explicit: persist the fingerprint client-side and pass the identical one to check_watches; use required_skills to keep sales/solutions-architect roles out; use `title` to watch for roles no skill tag names. There is no explicit statement of when NOT to register a watch (e.g. use search_jobs for a one-time query), which keeps it just short of a 5.

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