jobwatch

Overview Schema Source Related Servers Discussions Admin

mark_job

DestructiveIdempotent

Record or update a tracked job's status, notes, next steps, follow-up dates, or posting details to keep job-search records current.

Instructions

Record a job's status: new, shown, queued (to apply to next), applied, screening, interviewing, offer, rejected, withdrawn or skipped (omit status to keep it and only update the rest). key is the job's key, its posting id, or its company's name when that names one job (the one queued or applied to there); when it names several, nothing changes and the error lists them. Use applied only after the person has submitted the application themselves. add_note adds a dated line to the note, keeping what's there: prefer it for news ("recruiter replied: onsite only"); note replaces the whole note. next_step says what happens next ("recruiter screen Tuesday"); follow_up is the day to act (YYYY-MM-DD or +N days); applied_on is the day applied, if not today. url sets the link of a job added by hand (its posting, or the company's careers site once the posting is gone), and text its posting's text, pasted (found later, or from a copy once the posting is gone), so it can be scored and prepped. An empty string clears a field. For a job jobwatch doesn't track yet, use add_application.

Input Schema

TableJSON Schema

Name	Required	Description
`key`	Yes	The job: its key as other tools return it (source:board:posting id, e.g. greenhouse:acme:4012345), just the posting id, or the company's name when that names one job (the one queued or applied to there). When it matches several, the error lists their keys.
`url`	No	The link of a job added by hand: its posting, or the company's careers site once the posting is gone.
`note`	No	Replaces the whole note. Prefer add_note for news.
`text`	No	The posting's text, pasted (found later, or a copy once the posting is gone), so it can be scored and prepped.
`status`	No	The new status; omit to keep it and only update the rest. applied only after the person has submitted the application themselves.
`add_note`	No	A line to add to the note, dated today, keeping what's there ("recruiter replied: onsite only").
`follow_up`	No	A day: YYYY-MM-DD, or +N for N days from today. An empty string clears it.
`next_step`	No	What happens next ("recruiter screen Tuesday"). An empty string clears it.
`applied_on`	No	The day applied (YYYY-MM-DD), if not today.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed10 schema fields changedv0.2.3Oct 6, 2026

addedInput schema / properties / add_note / description

Added value: +"A line to add to the note, dated today, keeping what's there (\"recruiter replied: onsite only\")."

addedInput schema / properties / applied_on / description

Added value: +"The day applied (YYYY-MM-DD), if not today."

addedInput schema / properties / follow_up / description

Added value: +"A day: YYYY-MM-DD, or +N for N days from today. An empty string clears it."

addedInput schema / properties / key / description

Added value: +"The job: its key as other tools return it (source:board:posting id, e.g. greenhouse:acme:4012345), just the posting id, or the company's name when that names one job (the one queued or applied to there). When it matches several, the error lists their keys."

addedInput schema / properties / next_step / description

Added value: +"What happens next (\"recruiter screen Tuesday\"). An empty string clears it."

addedInput schema / properties / note / description

Added value: +"Replaces the whole note. Prefer add_note for news."

changedInput schema / properties / status / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "enum": [
+      "new",
+      "shown",
+      "queued",
+      "applied",
+      "screening",
+      "interviewing",
+      "offer",
+      "rejected",
+      "withdrawn",
+      "skipped"
+    ],
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / status / description

Added value: +"The new status; omit to keep it and only update the rest. applied only after the person has submitted the application themselves."

addedInput schema / properties / text / description

Added value: +"The posting's text, pasted (found later, or a copy once the posting is gone), so it can be scored and prepped."

addedInput schema / properties / url / description

Added value: +"The link of a job added by hand: its posting, or the company's careers site once the posting is gone."

First observedv0.1.0Oct 6, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations declare the safety profile (destructive, idempotent, non-read-only), and the description adds operational behavior well beyond them: ambiguous key matches change nothing and return the offending keys in the error, empty strings clear fields, note replaces while add_note appends, and url/text are only for hand-added jobs. This is substantive disclosure of side effects and failure modes.

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?

Purpose and status list are front-loaded, and each subsequent clause maps to a distinct parameter or edge case, so little is wasted. It is dense and long, with mild redundancy against the schema's own field descriptions, which keeps it from a 5.

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?

An output schema exists so return values need not be restated, and the description fills the remaining gaps: ambiguity handling, clearing semantics, append vs replace, and the boundary with add_application. An agent has everything needed to call this mutation correctly.

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 all nine parameters; the description largely mirrors those per-parameter blurbs. It still adds cross-parameter meaning the schema does not, notably the status-omission rule, the note vs add_note distinction, and queued meaning 'to apply to next'.

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?

The description opens with a specific verb+resource ('Record a job's status') and enumerates the full status vocabulary, making the operation unambiguous. It also explicitly contrasts itself with the sibling add_application for jobs not yet tracked, so an agent can distinguish the two 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?

It gives explicit when-to-use rules for the trickiest cases: 'applied only after the person has submitted the application themselves', 'omit status to keep it and only update the rest', 'prefer add_note for news', and 'For a job jobwatch doesn't track yet, use add_application'. Both the alternative tool and the selecting condition are named.

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

Deploy Server