Write a Job Description

You turn a vague "we need someone who..." into a job description that attracts the right people and that the rest of the hiring process can be built on. A good description states what the person will achieve in the first year, lists only the requirements you will actually screen and interview for, and contains nothing that screens people out on age, sex, race, religion, disability or any other protected characteristic. If your must-haves are wrong, everything downstream (sourcing, screening, interviews) will be wrong too, so the intake matters more than the prose.

When to use

• "Write a JD for a senior bookkeeper."
• "We're hiring our first designer, can you put an ad together?"
• "Our ad for the support lead got 200 applicants and none were any good."
• "Rewrite this old job description, it reads like it's from 2012."
• "Make this ad more inclusive."

What you need

• The hiring manager's answers to the intake questions in references/jd-template.md. If you cannot get a live conversation, send the questions through ask_teammate or ask the owner with clarify.
• The approved pay band and benefits. Never invent a salary. If there is no band, ask the owner; if they want market data, research it with web_search and present it as a range with sources, for them to decide.
• Work location, remote policy, and the countries or states the hire could live in. These decide which posting laws apply.
• Any existing ad, career page or handbook so the tone matches. Read them with read_file, or with browser_navigate if they are on the website.
• Access: the company's applicant tracking system (ATS) or job boards are a connected app or the agent's own browser signed in by the owner. You only draft; posting is the owner's call. If neither is available, hand the ad back as a file.

Method

1. Run the intake. Get answers to the intake questions, especially: why the role exists now, the three to five outcomes that define success at 6 and 12 months, who it reports to, the level, and what would make a candidate an instant no. Write outcomes as results ("close the month by working day 5 within 6 months"), not activities ("does month-end").
2. Separate must-haves from nice-to-haves. A must-have is something a person cannot learn in the first three months and without which they would fail.
   • Keep must-haves to five or fewer.
   • Everything else is a nice-to-have, and at most three of those.
   • For each must-have, write how you would see evidence of it in a CV or interview; if you cannot say, it is not a usable requirement.
3. Replace proxies with capabilities. Swap degree requirements for the skill the degree was standing in for, unless the qualification is a legal requirement for the work (for example a licensed profession). Express experience as capability ("has run payroll for 50+ people") rather than a year count where you can; "minimum years" and "maximum years" requirements can be indirect age discrimination in some countries, and "recent graduate" or "digital native" are direct age signals.
4. Pick a standard, searchable title. Use the title people actually search for at that level ("Senior Accountant", not "Numbers Ninja"). Put the level in the title if it changes who should apply.
5. Check the posting law for the role's location. Use web_search on the official government or regulator source for the location of the role and of likely applicants.
   • Check at least: whether a pay range must be included in the ad or given before interview (several US states and cities require ranges in postings, and the EU Pay Transparency Directive (EU) 2023/970 required member states to introduce pre-interview pay information by 7 June 2026, but many missed that date; confirm the current national rule), whether asking for salary history is banned, and any required equal opportunity or accessibility wording.
   • Record each rule with its source URL and the date you checked.
6. Draft with the template. Use the structure in references/jd-template.md: a two-sentence hook about the work and why it matters, the outcomes, how the person will work (team, tools, rhythm), must-haves, nice-to-haves, pay and benefits, the hiring process with stages and rough timing, the equal opportunity and adjustments statement, and how to apply.
7. Run the wording checks. Use execute_code with the stem lists in references/gendered-wording.md to count masculine-coded and feminine-coded words, and scan for the exclusionary phrases listed there.
   • Aim for balance, not purity: keep a coded word if it is the precise word for the job, and rewrite where a neutral word does the same work.
   • Remove physical requirements unless they are genuine and essential to the role, and then state them as the task ("lift boxes up to 20 kg regularly"), not as a trait of the person.
8. Check readability. Sentences under about 20 words on average, second person ("you will"), no internal jargon or acronyms without explanation, bullets that start with a verb. A competent applicant should understand the job in one read.
9. Hand it to the hiring manager and the owner. Show the draft, the must-have evidence table, and the legal checks with sources using show_card. Do not post anywhere until the owner approves.

Judgement calls

• A degree or licence is a genuine must-have only when the law or a regulator requires it for the work (for example a registered nurse, or an accountant who signs audits). Otherwise state the skill it stands for.
• If the hiring manager insists on a requirement that fails the evidence test, record it with their reason and raise it with the owner. Do not silently drop it or silently keep it.
• A remote role open to several countries needs a lawful way to employ in each one (a local entity, or an employer-of-record arrangement the owner already uses). Ask before you list a country.
• If the approved band sits well below what your sourced market research shows, tell the owner before posting, with the sources. An ad that underpays wastes everyone's time.
• If the company posts roles internally first, follow that rule and say so in the hand-over.

Output

• job-description-<role>.md containing:
  • the ad, ready to paste (400 to 700 words is the usual sweet spot; longer only if the role is unusual)
  • a short internal appendix: outcomes, must-haves with "evidence we will look for", nice-to-haves, deal-breakers, pay band source, and the legal checks with source URLs and dates
• A one-paragraph summary to the owner of what changed and why, and the list of open questions.
• A hand-over card for show_card:

Role: <title> · <level> · <location / remote rule>
Pay: <min to max, currency, period> (approved by <who>, <date>)
Must-haves (max 5)          | Evidence we will look for
<capability>                | <CV signal> / <interview signal>
Legal checks: <rule> (<official source>, checked <date>)
Wording: masculine-coded <n>, feminine-coded <n>; kept on purpose: <words and why>
Open questions for the hiring manager: <list>
Status: draft, not posted

Checks before you finish

• Every must-have has a stated way of seeing evidence, and there are five or fewer.
• No age, sex, family, nationality, religion, health or appearance signals; no "native speaker" (use "fluent written and spoken English" if language is genuinely needed).
• Pay range present if the location requires it, and matches the approved band exactly.
• Legal checks list the source and the date checked; nothing is stated as law without a source.
• Gendered wording count run and any remaining coded words are deliberate.
• The hiring process section tells applicants the stages and how to ask for adjustments.
• Nothing has been posted or sent; the owner has the draft.

Pitfalls

• The wish list. Twelve requirements describe a unicorn and deter strong applicants who meet eight. Cut to what you will actually screen on.
• Copying the last ad. Old ads carry old requirements nobody remembers adding. Start from the intake.
• Activity lists instead of outcomes. "Responsible for reporting" says nothing; "produce the weekly cash report the CEO uses to decide spending" says everything.
• Culture-fit language. "Work hard, play hard", "young and dynamic team" and "beer Fridays" signal who is not welcome. Describe how the team works instead.
• Vague pay. "Competitive salary" lowers response and may be unlawful where ranges are required. Use the real band.
• Inventing law. Posting rules change often and vary by city. Always cite the source you checked, or say it still needs checking.
• Hiding the hard parts. If the role has on-call duty, heavy travel or a messy starting point, say so. Surprises after the offer cause early resignations.
• Writing for the hiring manager instead of the applicant. Lead with what the person will do and achieve, not with the company's history.

See also: screen-cvs-fairly and structured-interview-kit, which reuse the must-haves you set here.