Skip to main content
Glama

Update a tracked job status

update_vacancy_status
Idempotent

Update the job-tracker status and/or notes of a tracked vacancy — e.g. mark it 'applied' after the user says they sent an application, or 'rejected' when they got a no. Statuses: new | applied | interview | offer | rejected | accepted. Status changes are recorded in the vacancy's history with the time of this call, or with occurred_at when given; setting the status it already has records nothing. notes replace the earlier notes as a whole. Returns the status before and after the call. At least one of status/notes is required. Returns 'not_found' for a missing or foreign id, 'invalid_payload' for an unknown status, an empty update, or an occurred_at that is unreadable, in the future, older than 90 days, sent without a status, or for a status that was never changed to.

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": {
      "input": "<input>"
    },
    "name": "update_vacancy_status"
  }
}

Input Schema

NameRequiredDescriptionDefault
inputYes

Output Schema

NameRequiredDescriptionDefault
idYes
notesNo
titleNoThe vacancy's title as the tracker shows it.
statusYes
changedYesWhether this call moved the status; false when it already had that status or only notes were sent.
previous_statusYesThe tracker status the vacancy had before this call.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / $defs / UpdateVacancyStatusInput / properties / notes / description
      Previous value: -"Replace the user's notes on this vacancy (plain text, ≤5000 chars; empty string clears)."New value: +"Replaces the user's notes on this vacancy as a whole; earlier notes are not kept (plain text, ≤5000 chars; empty string clears)."
    • addedInput schema / $defs / UpdateVacancyStatusInput / properties / occurred_at
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "The day the change happened when the user says it was earlier (e.g. 'I applied yesterday'): an ISO date (YYYY-MM-DD, read as noon UTC) or date-time, at most 90 days ago and not in the future. Sent with a new status it dates that change; with the status the vacancy already has it re-dates that status's latest change. The vacancy's history, its days in this status and follow-ups count from it; weekly counts keep the time the change was recorded.",
      +  "title": "Occurred At"
      +}
  2. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Goes well past the annotations: it discloses that changes are written into a per-vacancy history stamped with call time, that setting the current status records nothing (consistent with idempotentHint=true), and that notes are replaced wholesale with earlier notes lost — i.e. it explicitly names what gets destroyed, which is exactly the context destructiveHint=false alone cannot convey. It also enumerates the failure surface ('not_found', 'invalid_payload' with each cause) rather than leaving errors to be discovered at runtime.

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 the user-intent triggers are front-loaded, followed by semantics and then the error catalog; almost every clause carries operative information. The final sentence is a dense run-on enumerating five invalid_payload causes, and 'Returns the status before and after the call' partly duplicates the output schema, which costs some tightness.

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 single-nested-input mutation with annotations and an output schema, the description covers everything an agent needs: what changes, history/occurred_at semantics, no-op behavior, notes overwrite, and the full error taxonomy. Return values are summarized rather than re-specified, which is appropriate given an output schema exists.

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 description coverage is reported as 0%, so the description must carry the load, and it largely does: it fixes the status enum, explains that notes are a whole-value replacement, and spells out occurred_at constraints (max 90 days back, not future, requires a status, meaningless for a status never set). It leaves the date-format nuance (noon UTC reading of a bare date) and vacancy_id provenance to the schema, so a small remainder is still schema-dependent.

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+scope: 'Update the job-tracker status and/or notes of a tracked vacancy,' then anchors it with concrete user-intent examples ('mark it applied after the user says they sent an application'). It also enumerates the closed status vocabulary, so an agent knows exactly what the tool mutates without opening the 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?

Gives clear situational triggers keyed to user utterances (they sent an application, they got a rejection) and states the hard precondition 'at least one of status/notes is required.' It stops short of routing to or away from siblings such as answer_vacancy_status or analyze_tracked_vacancy, so the when-not-to-use side 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.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.