---
name: assess-job-description
description: Score how cleanly a job description can be turned into a structured role profile, and say what to fix in the source. Use when someone shares a job description or job ad and wants it reviewed, critiqued, scored, improved or rewritten; when they ask why their job postings are inconsistent or hard to work with; or before generating a role profile from an existing JD. Requires the WorkforceGPT MCP server.
---

# Assessing a job description

WorkforceGPT scores a job description on how much of a structured role profile
can be *extracted* from it rather than *invented*. The score answers one
question: if we transformed this document into responsibilities, skills,
proficiencies and qualifications, how much of the result would be sourced from
what the person actually wrote?

That is narrower than "is this a good job ad", and keeping the distinction
straight is most of using this well.

The tool is `assess_job_description`. It takes the document as
`job_description` (text), with an optional `filename` used only as a label in
the account's history.

## When to reach for it

Obvious triggers: "score this JD", "how good is this job description",
"assess this posting".

Less obvious, and worth catching:

- Someone pastes a job description and asks you to improve or rewrite it. Score
  it first — the diagnostics tell you exactly what is missing, which is a far
  better rewrite brief than your own impression.
- Someone complains their job descriptions are inconsistent across teams. Score
  two or three and compare `sections_missing`; the pattern is usually the same
  two sections absent everywhere.
- Someone wants a role profile built from a JD they already have. Assess before
  generating, because a low score predicts a role profile that reads well and
  means little.

## Spend the quota deliberately

Assessments through this API are **metered** — the allowance is small, typically
three per account, and `get_account_status` reports what is left.

Before running one:

- Call `get_account_status` if you have not this session. Finding out the
  account is empty *after* composing a request wastes the person's time. The
  number to read is `quota.assessments.remaining`.
- If they have handed you a folder of job descriptions, do not loop. Say how
  many calls it would take and how many they have, and ask. Assessing in the
  web app is free and unmetered — that is the right answer for bulk.
- A refusal comes back as a tool result with `error: "assessment_quota_exhausted"`,
  the full quota block, and an `upgrade_url`. Relay it. Do not retry.

## Reading the result

You get `overall_score` (0–100), `grade`, a `band`, and four `sub_scores`. The
band arrives with `band_meaning` and `recommended_action` already written — use
them rather than inventing your own gloss.

The sub-scores are where the actual diagnosis lives, and they fail in different
ways:

| Sub-score | Low means | The fix |
|---|---|---|
| `section_coverage` | Target sections are simply absent from the source | Add the sections in `sections_missing` |
| `inference_burden` | The model would be writing, not extracting | Same — this tracks coverage |
| `ambiguity` | Placeholders (`TBD`, `n/a`), or "X, Y or Z" alternative lists | Replace placeholders; enumerate alternatives separately |
| `format_clarity` | No headings, no bullets — a wall of prose | Add section headings |

Two documents can score the same overall and need completely different work.
`section_coverage` 0 with `ambiguity` 100 is a clear, well-written page that
happens to omit most of what a role profile needs. Both at 50 is a document
that is half-structured and vague throughout. Say which one you are looking at.

## What a low score does not mean

**It is not a judgment of the job, the team, or the person who wrote it.** A
well-run role with a precisely scoped remit can have a terrible score, because
the *document* is three paragraphs of prose. Leading with "this job description
scored 31" sounds like criticism of their work. Lead with what is missing and
what adding it would buy them.

It also is not a hiring-quality signal. Nothing here evaluates whether the
requirements are reasonable, whether the seniority matches the responsibilities,
or whether the posting will attract good candidates. Say so if asked.

## The most useful thing you can do with a low score

Fix the document. The `recommendations` and `issues` arrays name specific,
addressable problems — missing sections, placeholder values, prose with no
structure — and rewriting a job description is something you can do directly,
right there, at no quota cost at all.

That is usually worth more to the person than the number was. Offer it.

## Handing off to generation

If the band is `high`, generating a role profile from this JD is a reasonable
next step — see the `build-role-profile` skill.

If it is `medium` or `low`, say what will happen: the missing sections get
inferred rather than extracted, so the profile will be plausible rather than
sourced, and a reviewer needs to check exactly the sections in
`sections_missing`. Generation spends a credit and there are only a few, so
this is a decision for the person, not for you.

## Practical notes

- The tool takes the job description as **text**. There is no file upload over
  MCP. If you are holding a PDF or DOCX, extract the text first, or point them
  at the web app, which converts documents itself.
- It runs synchronously and does real work. Allow a generous client timeout
  rather than the default few seconds.
- `get_assessment` and `list_my_assessments` reach past results, including ones
  run in the web app, so you can refer back without spending anything.
- A run that fails on our side does **not** consume quota.