Skip to main content
Glama

Update a job's application status

freeapply_update_job
DestructiveIdempotent

Update a claimed job's application status—applied, skipped, needs info, account required, or blocked—and record outcomes with truthfulness checks.

Instructions

Sets a claimed job's status: your side of the application (employer's response: freeapply_record_outcome; adding a job: freeapply_claim_job). Use: after a submit (applied); giving up (skipped, failed); when the user must act: needs_info with the form's questions, needs_account with the sign-up page, blocked by a check you can't pass. Behavior: replaces the status. Enforced: applied needs a fresh freeapply_clear_to_submit clearance for this job; cover_text must pass the truthfulness check; an applied job only the user can change. needs_info questions go to the Needs you tab and re-queue the job once answered; if the user already answered them all, refused with the answers to use. A field marked for one status is refused with any other. Returns: {job_id, status} and when relevant: already_waiting; questions (each added, duplicate, grouped or already_answered, with its answer), questions_added; same_account (needs_account: jobs sharing one sign-up card); same_site (blocked: jobs blocked on the same site). Errors: an unknown job_id or a broken rule, saying what is missing.

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": {
      "job_id": "<job_id>",
      "status": "<status>"
    },
    "name": "freeapply_update_job"
  }
}

Input Schema

NameRequiredDescriptionDefault
noteNoWhat happened, for the user: one plain sentence, no technical terms, e.g. "The site asked to prove you're a person."
job_idYesThe job's id, as returned by freeapply_claim_job or freeapply_list_jobs.
methodNoapplied only: how it was submitted.
statusYesNew status: found (qualified, not yet worked), ready (documents prepared, not yet submitted), applied (application submitted), skipped (filtered out (see status_note)), needs_info (a form asked something the profile does not answer), needs_account (employer site requires creating an account), blocked (CAPTCHA, verification code or site warning), failed (error while applying).
questionsNoneeds_info only, at least one: the form's unanswered questions, each with a plain prompt and the simplest kind of answer that fits.
cover_pathNoapplied only: the letter file sent, if not the saved one.
cover_textNoapplied only: the letter sent, if not the saved one.
account_urlNoneeds_account only: the site's sign-up page. Jobs with the same one share a card; one "I made the account" re-queues them all. Default: the application link, so jobs rarely share.
letter_sentNoapplied only; required when a letter is saved for the job (freeapply_check_text save): true if attached or pasted, false if not (letter dropped from the record).
resume_pathNoapplied only: the résumé file sent, if not the documents copy (recorded by default).
confirmationNoapplied only: the confirmation text or number the site showed.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed13 schema fields changedv1.0.4
    • changedInput schema / properties / account_url / description
      Previous value: -"For needs_account: the site's sign-up page. Jobs with the same one share a card, and one \"I made the account\" re-queues them all; without it the application link is used, so jobs rarely share."New value: +"needs_account only: the site's sign-up page. Jobs with the same one share a card; one \"I made the account\" re-queues them all. Default: the application link, so jobs rarely share."
    • changedInput schema / properties / confirmation / description
      Previous value: -"For applied: the confirmation text or number the site showed."New value: +"applied only: the confirmation text or number the site showed."
    • changedInput schema / properties / cover_path / description
      Previous value: -"For applied: the cover-letter file sent, if not the saved one. Optional."New value: +"applied only: the letter file sent, if not the saved one."
    • changedInput schema / properties / cover_text / description
      Previous value: -"For applied: the cover letter sent, if not the saved one. Optional."New value: +"applied only: the letter sent, if not the saved one."
    • addedInput schema / properties / letter_sent
      Added value: +{
      +  "description": "applied only; required when a letter is saved for the job (freeapply_check_text save): true if attached or pasted, false if not (letter dropped from the record).",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / method / description
      Previous value: -"For applied: how it was submitted."New value: +"applied only: how it was submitted."
    • changedInput schema / properties / note / description
      Previous value: -"What happened, for the user, e.g. \"The site asked to prove you're a person.\""New value: +"What happened, for the user: one plain sentence, no technical terms, e.g. \"The site asked to prove you're a person.\""
    • changedInput schema / properties / questions / description
      Previous value: -"For needs_info: the form's unanswered questions, each with a plain prompt and the simplest kind of answer that fits."New value: +"needs_info only, at least one: the form's unanswered questions, each with a plain prompt and the simplest kind of answer that fits."
    • changedInput schema / properties / questions / items / properties / label / description
      Previous value: -"The question exactly as the form words it (you need it to fill the form later)."New value: +"Exactly as the form words it (needed to fill the form later)."
    • changedInput schema / properties / questions / items / properties / options / description
      Previous value: -"Choices, for choice or multi, worded as the form offers them."New value: +"For choice or multi: the choices as the form words them."
    • changedInput schema / properties / questions / items / properties / prompt / description
      Previous value: -"The question in plain words for the user: one short sentence, no form codes or jargon, e.g. \"Can you work weekends?\" for \"Availability - Sat/Sun shifts (Y/N)*\"."New value: +"Plain words for the user: one short sentence, no form codes or jargon, e.g. \"Can you work weekends?\" for \"Availability - Sat/Sun shifts (Y/N)*\"."
    • changedInput schema / properties / questions / items / properties / type / description
      Previous value: -"Kind of answer: yesno or choice for fixed answers (one; buttons up to 5 options, a dropdown for more), multi (all that apply), number, date, or text or textarea."New value: +"yesno or choice: one fixed answer (buttons up to 5 options, else a dropdown); multi: all that apply; number; date; text or textarea."
    • changedInput schema / properties / resume_path / description
      Previous value: -"For applied: the résumé file sent, if not the documents copy. Optional."New value: +"applied only: the résumé file sent, if not the documents copy (recorded by default)."
  2. Changed10 schema fields changedv1.0.2
    • changedInput schema / properties / account_url / description
      Previous value: -"For needs_account: the full link to the page where the user makes the account (the site's sign-up page). Jobs whose account is made at the same address share one card, and one \"I made the account\" re-queues them all; without it the application link is used, so jobs rarely share."New value: +"For needs_account: the site's sign-up page. Jobs with the same one share a card, and one \"I made the account\" re-queues them all; without it the application link is used, so jobs rarely share."
    • changedInput schema / properties / confirmation / description
      Previous value: -"Confirmation text or number the site showed."New value: +"For applied: the confirmation text or number the site showed."
    • changedInput schema / properties / cover_path / description
      Previous value: -"Path of the cover-letter file submitted."New value: +"For applied: the cover-letter file sent, if not the saved one. Optional."
    • changedInput schema / properties / cover_text / description
      Previous value: -"The cover letter actually submitted; it must pass the truthfulness check."New value: +"For applied: the cover letter sent, if not the saved one. Optional."
    • changedInput schema / properties / job_id / description
      Previous value: -"The job's id, as returned by freeapply_add_job or freeapply_list_jobs."New value: +"The job's id, as returned by freeapply_claim_job or freeapply_list_jobs."
    • changedInput schema / properties / method / description
      Previous value: -"How it was submitted, for applied."New value: +"For applied: how it was submitted."
    • changedInput schema / properties / note / description
      Previous value: -"What happened, in one plain sentence the user will read on the dashboard: no code, page elements or technical terms, e.g. \"The site asked to prove you're a person.\""New value: +"What happened, for the user, e.g. \"The site asked to prove you're a person.\""
    • changedInput schema / properties / questions / description
      Previous value: -"For needs_info: the form's unanswered questions. Give each a plain prompt and the simplest kind of answer that fits: a choice with options (or yesno) when the form offers fixed answers, multi when it takes several, text otherwise."New value: +"For needs_info: the form's unanswered questions, each with a plain prompt and the simplest kind of answer that fits."
    • changedInput schema / properties / questions / items / properties / type / description
      Previous value: -"Kind of answer: text or textarea (open-ended, short or long), yesno, choice (pick one; buttons for up to 5 options, a dropdown for more), multi (pick all that apply), number or date."New value: +"Kind of answer: yesno or choice for fixed answers (one; buttons up to 5 options, a dropdown for more), multi (all that apply), number, date, or text or textarea."
    • changedInput schema / properties / resume_path / description
      Previous value: -"Path of the résumé file submitted."New value: +"For applied: the résumé file sent, if not the documents copy. Optional."
  3. Changed15 schema fields changedv1.0.1
    • addedInput schema / properties / account_url
      Added value: +{
      +  "description": "For needs_account: the full link to the page where the user makes the account (the site's sign-up page). Jobs whose account is made at the same address share one card, and one \"I made the account\" re-queues them all; without it the application link is used, so jobs rarely share.",
      +  "type": "string"
      +}
    • addedInput schema / properties / confirmation / description
      Added value: +"Confirmation text or number the site showed."
    • addedInput schema / properties / cover_path / description
      Added value: +"Path of the cover-letter file submitted."
    • addedInput schema / properties / cover_text / description
      Added value: +"The cover letter actually submitted; it must pass the truthfulness check."
    • addedInput schema / properties / job_id / description
      Added value: +"The job's id, as returned by freeapply_add_job or freeapply_list_jobs."
    • addedInput schema / properties / job_id / minimum
      Added value: +1
    • addedInput schema / properties / method / description
      Added value: +"How it was submitted, for applied."
    • addedInput schema / properties / method / enum
      Added value: +[
      +  "easy_apply",
      +  "external",
      +  "email"
      +]
    • addedInput schema / properties / note / description
      Added value: +"What happened, in one plain sentence the user will read on the dashboard: no code, page elements or technical terms, e.g. \"The site asked to prove you're a person.\""
    • addedInput schema / properties / questions / description
      Added value: +"For needs_info: the form's unanswered questions. Give each a plain prompt and the simplest kind of answer that fits: a choice with options (or yesno) when the form offers fixed answers, multi when it takes several, text otherwise."
    • addedInput schema / properties / questions / items / properties
      Added value: +{
      +  "help": {
      +    "description": "Optional one-line hint the user sees under the prompt: why it's asked or what a good answer looks like.",
      +    "type": "string"
      +  },
      +  "label": {
      +    "description": "The question exactly as the form words it (you need it to fill the form later).",
      +    "type": "string"
      +  },
      +  "options": {
      +    "description": "Choices, for choice or multi, worded as the form offers them.",
      +    "items": {
      +      "type": "string"
      +    },
      +    "type": "array"
      +  },
      +  "prompt": {
      +    "description": "The question in plain words for the user: one short sentence, no form codes or jargon, e.g. \"Can you work weekends?\" for \"Availability - Sat/Sun shifts (Y/N)*\".",
      +    "type": "string"
      +  },
      +  "required": {
      +    "description": "Whether the form requires it.",
      +    "type": "boolean"
      +  },
      +  "type": {
      +    "description": "Kind of answer: text or textarea (open-ended, short or long), yesno, choice (pick one; buttons for up to 5 options, a dropdown for more), multi (pick all that apply), number or date.",
      +    "enum": [
      +      "text",
      +      "textarea",
      +      "yesno",
      +      "choice",
      +      "multi",
      +      "number",
      +      "date"
      +    ],
      +    "type": "string"
      +  }
      +}
    • addedInput schema / properties / questions / items / required
      Added value: +[
      +  "label"
      +]
    • addedInput schema / properties / resume_path / description
      Added value: +"Path of the résumé file submitted."
    • addedInput schema / properties / status / description
      Added value: +"New status: found (qualified, not yet worked), ready (documents prepared, not yet submitted), applied (application submitted), skipped (filtered out (see status_note)), needs_info (a form asked something the profile does not answer), needs_account (employer site requires creating an account), blocked (CAPTCHA, verification code or site warning), failed (error while applying)."
    • addedInput schema / properties / status / enum
      Added value: +[
      +  "found",
      +  "ready",
      +  "applied",
      +  "skipped",
      +  "needs_info",
      +  "needs_account",
      +  "blocked",
      +  "failed"
      +]
  4. First observedv0.1.0

TDQS

A4.9/5.0
Behavior5/5

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

Beyond annotations, the description discloses key behavior: status replacement, fresh clearance enforcement for applied, truthfulness checks on cover_text, the rule that applied jobs only the user can change, needs_info re-queue behavior, and refusal rules for status-specific fields. It also describes return fields and error conditions, giving the agent operational context needed to invoke it safely.

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

Conciseness5/5

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

The description is front-loaded and organized into clear Use, Behavior, Returns, and Errors sections. Despite its length, every section earns its place by covering a complex multi-status tool with 11 parameters.

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?

There is no output schema, but the description supplies the relevant return shape and error behavior. Combined with annotations and full schema coverage, it gives enough information for an agent to call the tool correctly across statuses and edge cases.

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 100%, so the schema already carries most parameter meaning and baseline is 3. The description adds conditional semantics beyond the schema, such as applied-only enforcement, needs_info question handling, needs_account sign-up page behavior, and refusal when a field is supplied for the wrong status.

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 gives a specific verb and resource: it sets a claimed job's application status. It immediately distinguishes the tool from siblings by naming freeapply_record_outcome for employer responses and freeapply_claim_job for adding jobs, so an agent can identify the correct tool 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 Guidelines5/5

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

It explicitly maps statuses to situations: applied after submit, skipped/failed when giving up, needs_info/needs_account/blocked when the user must act. It also names alternative tools for adjacent operations, leaving little ambiguity about when to use this tool versus siblings.

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