Skip to main content
Glama

mark_job

DestructiveIdempotent

Update a job's application status, notes, next steps, interview round, and follow-up date. Adds posting text or links to enable scoring and prep.

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"), with its date and time; round says which interview it is (see its description), so it counts as a meeting without depending on its words; 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); when the job has no posting text and the link is to one job on a supported board, the posting is read from it (text, pay, places), so it can be scored. text sets 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. Queuing a job that's (maybe) the same opening as one applied to or queued still queues it, and the reply ends with the warning: tell the person.

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": {
      "key": "<key>"
    },
    "name": "mark_job"
  }
}

Input Schema

NameRequiredDescriptionDefault
keyYesThe 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.
urlNoThe link of a job added by hand: its posting, or the company's careers site once the posting is gone.
noteNoReplaces the whole note. Prefer add_note for news.
textNoThe posting's text, pasted (found later, or a copy once the posting is gone), so it can be scored and prepped.
roundNoWhich interview the next step is: recruiter_screen, hiring_manager, technical, system_design, panel (onsite or loop), executive (VP, director, CXO), hr, informal (coffee, in-person talk, referral chat) or offer_call. Set it with a next step that has a date and time: it makes the step a meeting on the Interviews tab and in the calendar feed, whatever its words. An empty string clears it.
statusNoThe new status; omit to keep it and only update the rest. applied only after the person has submitted the application themselves.
add_noteNoA line to add to the note, dated today, keeping what's there ("recruiter replied: onsite only").
follow_upNoA day: YYYY-MM-DD, or +N for N days from today. An empty string clears it.
next_stepNoWhat happens next ("recruiter screen Tuesday"). An empty string clears it.
applied_onNoThe day applied (YYYY-MM-DD), if not today.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.10.0
    • changedInput schema / properties / status / anyOf
      Previous value: -[
      -  {
      -    "enum": [
      -      "new",
      -      "shown",
      -      "queued",
      -      "applied",
      -      "screening",
      -      "interviewing",
      -      "offer",
      -      "rejected",
      -      "withdrawn",
      -      "skipped"
      -    ],
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "enum": [
      +      "new",
      +      "shown",
      +      "queued",
      +      "applied",
      +      "screening",
      +      "interviewing",
      +      "offer",
      +      "rejected",
      +      "withdrawn",
      +      "skipped",
      +      "snoozed"
      +    ],
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
  2. Changed1 schema field changedv0.7.0
    • addedInput schema / properties / round
      Added value: +{
      +  "anyOf": [
      +    {
      +      "enum": [
      +        "recruiter_screen",
      +        "hiring_manager",
      +        "technical",
      +        "system_design",
      +        "panel",
      +        "executive",
      +        "hr",
      +        "informal",
      +        "offer_call",
      +        ""
      +      ],
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Which interview the next step is: recruiter_screen, hiring_manager, technical, system_design, panel (onsite or loop), executive (VP, director, CXO), hr, informal (coffee, in-person talk, referral chat) or offer_call. Set it with a next step that has a date and time: it makes the step a meeting on the Interviews tab and in the calendar feed, whatever its words. An empty string clears it.",
      +  "title": "Round"
      +}
  3. Changed10 schema fields changedv0.2.3
    • 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."
  4. First observedv0.1.0

TDQS

A4.5/5.0
Behavior5/5

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

Annotations declare destructiveHint=true and idempotentHint=true but not the specifics; the description supplies them: note replaces the whole note while add_note appends dated lines, an empty string clears a field, omitting status preserves it, url can trigger reading a posting from a supported board (text, pay, places), and queuing a possible duplicate succeeds but returns a warning to relay to the person.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the status list well, but the body is a long run-on paragraph that largely restates the schema field-by-field, so much of its length does not earn new information. The final duplicate-queue caveat is buried at the end where it is easy to miss.

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 10-parameter mutation tool with side effects, the description covers what gets overwritten vs appended, key resolution failure behavior, clear-empty-string semantics, and side-effectful url/text handling. Return values are covered by the existing output schema, so nothing an agent needs is missing.

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 description coverage is 100% and each parameter's schema text already carries almost all of this meaning (status enum, note vs add_note, follow_up +N format, applied_on, empty-string clearing). The description adds only marginal extras, such as url pulling posting text/pay/places on supported boards and the duplicate-queue warning. Baseline 3 applies when the schema does the heavy lifting.

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?

Opens with a specific verb+resource ("Record a job's status") and enumerates the whole status domain, then extends to the ancillary fields (note, next_step, follow_up, url, text). It is clearly distinguishable from add_application, which it names as the path for jobs not yet tracked.

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?

Explicit routing rules: use add_application for jobs jobwatch doesn't track, prefer add_note "for news" over note, and use applied only after the person submitted the application themselves. It also states the when-not case for ambiguous keys (several matches → nothing changes, error lists them).

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