---
name: build-role-profile
description: Generate a structured role profile — description, responsibilities, skills with proficiency levels, and qualifications — from a job title and optionally an existing job description. Use when someone needs a job profile, role definition, competency model or skills framework for a position they are hiring for, restructuring, or documenting. Requires the WorkforceGPT MCP server.
---

# Building a role profile

WorkforceGPT builds a role profile by matching the title against labor-market
occupation data (O*NET) and drawing skills from it. Where an uploaded job
description is supplied, skills can instead come from that document. Skills are
never invented by a language model — they come from labor-market data or from
the customer's own text, and nowhere else.

Two things follow from that, and they are most of what you need to know: the
**title** determines whether there is anything to match against, and a **job
description** is the fallback when there isn't.

The tool is `generate_role`. It requires `role_title` and `company_name`, and
optionally takes `job_description`,
`use_job_description_if_title_not_found`, `include_learning_resources` and
`learning_resources_source`.

## Getting the title right

`role_title` is the part that decides whether the call succeeds.

The match is against an *occupation*, not against a company's internal
nomenclature. Strip everything that is local to one organization:

| Instead of | Send |
|---|---|
| `Senior Staff Engineer Static Timing` | `Staff Engineer` or `Electronics Engineer` |
| `P4 Backend Engineer II, Payments Platform` | `Backend Engineer` |
| `AE — Mid-Market (SMB West)` | `Account Executive` |
| `RCM Specialist` | `Revenue Cycle Specialist` |
| `Head of People Ops` | `Human Resources Manager` |

Rules of thumb: drop internal leveling (P4, II, Band 3), drop team and
territory names, spell out acronyms, and prefer the phrase someone outside the
company would recognize. Seniority words that are widely understood — Senior,
Lead, Principal, Director — are usually fine to keep.

If the person gave you a description rather than a title ("we need someone to
run our data team"), propose a title and check it with them before spending
anything. Getting this wrong costs a credit.

## When to attach a job description

Pass `job_description` when:

- the title is unusual, internal, or you are not confident it will match;
- the person has an existing JD and wants the profile to reflect *their* role
  rather than the generic occupation;
- a previous attempt came back **Role Not Found**.

With a JD attached, `use_job_description_if_title_not_found` defaults to true,
which lets the profile be built from the document when the labor market has no
match. Without a JD that setting does nothing — there would be no source to
fall back on.

If the person has a JD, consider assessing it first (see the
`assess-job-description` skill). A JD that scores badly makes a role profile
that reads well and means little.

## Before you spend a credit

Generations are **limited** — typically three per account — and one completed
generation is one credit gone.

- Call `get_account_status` first. It reports `remaining` and
  `generation_in_progress`.
- ⚠️ `remaining` does **not** drop when a generation starts. Credits count
  *completed* roles, so a run that fails costs nothing. What stops a second
  call meanwhile is `generation_in_progress`. Read both.
- **Confirm the title and company with the person before calling.** This is
  their credit, they have very few, and a title you guessed is the most likely
  reason to waste one.
- Only one generation runs at a time. Starting another while one is in flight
  returns `generation_in_progress` rather than queueing.

## Running it

`generate_role` returns immediately with a `role_id`. It does not return a
profile.

Poll `check_role_status` with that id about every thirty seconds — not
continuously — until `status` leaves `pending`. A generation still running
after the server's timeout is marked `failed`, and a failed generation does not
spend a credit.

Tell the person it is running and roughly how you will report back. Do not sit
silently in a long poll loop.

## Reading the output

The completed `result` carries raw numbers where the web app shows labels.
Translate them; presenting "importance: 1" is actively misleading, since 1 reads
like the lowest.

- `importance_to_role` — **1 = High, 2 = Medium, 3 = Low**
- `proficiency_level_required` — **1 = Novice, 2 = Intermediate, 3 = Advanced,
  4 = Expert**

Skills may also carry `hot_technology` and `in_demand` booleans from O*NET.

⚠️ **Absence means the source gave no signal, not that the skill is out of
favor.** Never render a missing flag as a negative — no "not in demand", no
empty badge. Mention them only where they are true.

Group by importance when you present the profile. A flat list of thirty skills
is harder to use than three short ones.

## When it fails

**Role Not Found** means the labor market could not normalize the title. Two
fixes, in order:

1. Broaden the title — this is usually an internal name that needs translating
   into an occupation. See the table above.
2. Attach the job description and let it build from that instead.

Failures do not spend a credit, so retrying with a better title is free. Say
which of the two you are doing and why.

## What you cannot do from here

- **Publishing.** Roles can be published to a public, search-indexed library
  under the account holder's name, but there is no tool for it and no scope
  that would allow one — that is a decision about someone's public footprint
  and not one an agent should take on their behalf. Point them at the web app.
- **Editing or deleting a generated role.** Read-only from here.
- **Uploading a file.** The job description arrives as text; extract it first
  if you are holding a PDF.

## Seeing an example first

`search_public_roles` and `get_public_role` need no account at all. If someone
wants to see what a finished profile looks like before committing a credit —
or before signing up — that is the cheapest way to show them.