Skip to main content
Glama

Update a job's application status

freeapply_update_job
DestructiveIdempotent

Update a claimed job's status to record that you applied, skipped it, failed, need form answers or an account, or are blocked.

Instructions

Records your side of an application by setting a tracked job's status. Unlike freeapply_record_outcome (what the employer did) and freeapply_claim_job (adding a job), it changes a job you already claimed. Use it after a submit (applied), when you give up on a job (skipped or failed), and 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. Not for employer replies. Behavior: replaces the job's status. Enforced: applied needs a fresh clearance from freeapply_clear_to_submit for this job; cover_text must pass the truthfulness check; a job already applied to 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, the call is refused with the answers to use. Parameters: note is one plain sentence the user reads, with no technical terms. Some fields go with one status and are refused with any other: questions (at least one) with needs_info; account_url with needs_account; method, confirmation, resume_path, cover_path and cover_text with applied. The résumé copy and the letter saved by freeapply_check_text are recorded by default; pass the file and letter fields only when you sent something else. Returns: {job_id, status}, and when relevant: already_waiting; questions (each added, duplicate, grouped or already_answered, with its answer) and 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.

Input Schema

NameRequiredDescriptionDefault
noteNoWhat happened, for the user, 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.
methodNoFor applied: 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).
questionsNoFor needs_info: the form's unanswered questions, each with a plain prompt and the simplest kind of answer that fits.
cover_pathNoFor applied: the cover-letter file sent, if not the saved one. Optional.
cover_textNoFor applied: the cover letter sent, if not the saved one. Optional.
account_urlNoFor 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.
resume_pathNoFor applied: the résumé file sent, if not the documents copy. Optional.
confirmationNoFor applied: the confirmation text or number the site showed.

Schema Changelog

Changes observed during successful MCP inspections.

  1. 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."
  2. 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"
      +]
  3. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Goes far beyond the annotations (destructive, idempotent, non-read-only) by disclosing enforcement rules: applied requires fresh clearance from freeapply_clear_to_submit, cover_text passes truthfulness check, only the user can change an already-applied job, needs_info re-queues the job, and a refusal returns answers when all questions were already answered. These are behavioral traits an agent cannot infer from annotations alone, and none contradict them.

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?

It is long but tightly structured with labeled sections (Behavior, Parameters, Returns, Errors) and the purpose is front-loaded. Nearly every sentence carries actionable information, though the density could be trimmed slightly 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?

With 10 parameters and no output schema, the description fills the gap by documenting the return shape ({job_id, status}, already_waiting, questions, same_account, same_site) and error behavior. Together with parameter and behavior sections, an agent has everything needed to invoke it 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 description coverage is 100%, so the baseline is 3, but the description adds meaningful conditional semantics: which fields pair with which status and are otherwise refused, and that résumé/letter defaults are recorded unless overridden. It also clarifies that 'note' is one plain sentence for the user. This is real value beyond the schema, though some of the field-status coupling is already present in the schema descriptions.

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 ('Records your side of an application by setting a tracked job's status') and explicitly distinguishes itself from freeapply_record_outcome (employer side) and freeapply_claim_job (adding a job). An agent can identify this as the status-mutation 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?

Explicitly names when to use it: after a submit (applied), when giving up (skipped/failed), and when the user must act (needs_info, needs_account, blocked), plus a clear exclusion ('Not for employer replies'). The status triggers function as concrete invocation guidance.

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