When 92% means different things
A UX writing case study on strings that state their own context in a plain-text interface.
Sweepy is a terminal-based job-search tool. The interface draws with box-drawing characters and colored text, and it reads keyboard input. An explanation has to live in the text itself, because a tooltip has nowhere to appear. The launchpad clips its status line at the frame edge rather than wrapping. A string either finishes inside the width or loses its ending.
One rule came out of that. Every string states its own context. Score labels state who wrote the number. Status copy follows the same discipline, from the launchpad's bottom line down to each prompt's format hint. The score is the hard case, because a percentage looks informative regardless of whether the reader knows how the tool produced it.
Two percentages, two questions
Sweepy scores a posting against a resume in two different ways.
The first is the deterministic scorer, and every sweep runs it. sweepy opens the launchpad, and START SWEEP scores every card the sweep finds. sweepy --run repeats the last saved profile without opening the wizard. This pass compares two documents. It counts shared words between the resume and the posting, blending requirement overlap at 60% with keyword overlap at 40%, then scaling the result by resume.keywords_weight. A term counts only when it appears on both sides. The scorer never reasons about whether the reader could do the job.
The second is an agent assessment, available through the Model Context Protocol (MCP). An agent reads the parsed resume and the posting together, then reasons about how well the reader fits the role. It submits its own percentage through submit_judgments.
A shared-word count and an agent's judgment answer different questions. A count of shared words measures overlap, not fit, so the label has to name the writer. The count reports how much text the resume and the posting share. The agent judges how well one person suits one job. A resume can restate a posting word for word and still describe a weak fit. A resume in other vocabulary can describe a strong one. The word count spots the first case and misses the second, and the agent can weigh both.
The card shows one score. The most recent writer sets it, and an assessment re-ranks the report around the new value. The judgment replaces the deterministic score instead of sitting beside it. A bare percentage hides which of the two the reader has.
The copy had to state the writer inside the badge line, before the reader opens a listing. The rest of the interface follows the same rule.
From launchpad to results
The flow runs launchpad → setup wizard → sweep → results. When a sweep outlasts the client's tool-call limit, it hands off to a pollable status that stays live until the run finishes.
Cards 3 through 8 follow that order. Card 2 covers the score, which exists only after a sweep ends and is the case the rest of the page builds toward. Card 1 states the problem, and card 9 states the constraint behind every string between them.
One score slot, two authors
One score slot, two possible authors. Every sweep scores each card with the deterministic overlap count. But an MCP assessment overwrites that number with its own reasoning. Without a clear labeling difference, a reader can't tell which writer set the score, and can't calibrate trust. The content problem was to differentiate the writer inside the badge line, in the space of a few words.
Telling a count from a judgment
Same profile, same number, two writers. An agent set the first card, so it reads 92% MATCH. The deterministic scorer set the second, so it reads 92% KEYWORD OVERLAP. The label identifies the writer. A reader who sees only 92% has no way to tell the two apart. The assessment overwrites the overlap score in the same slot, because the count and the judgment answer different questions.
92% KEYWORD OVERLAPmeans the shared-word count, comparing the resume to the posting.92% MATCHmeans the number an agent reached by reasoning about how well the reader fits the role.
A sweep writes the count on each card it produces, whether it starts in the terminal or through run_sweep over MCP. Only a submitted match_pct replaces it with MATCH.
The PDF rank line repeats the label in brackets: #1 // COMPANY | [92% MATCH] or [92% KEYWORD OVERLAP]. The CSV writes match_value next to match_kind, which gives the reader the same fact in machine-readable form. A third score can appear beside the match score. [88% PORTFOLIO FIT] prints its own label for the same reason, because your samples answer a different question than your resume does.
The application badge reads in text first, color second. [STANDARD / QUICK APPLY] marks a standard submission, and [EXTENDED RESPONSES REQUIRED] marks a role that requires writing samples. The third card prints [EXTENDED RESPONSES REQUIRED] on a rank line that also lists the resume track. Both labels work without color, which matters for accessibility and for terminals that don't render it.
Identity, scope, and readiness in one line
Current profile: none loaded / build one to start states the missing state and the next action in one line. Current profile: Alex Rivera / 4 titles / Ready confirms the name in the first slot and readiness in the last. Each slash separates one answer from the next, and the line clips at the frame edge instead of wrapping. Resume missing replaces Ready when the saved profile has no resume path.
In a terminal the status line is the only persistent context. It reads as a header and a readiness indicator at once.
Verb, object, then the reader's goal
START SWEEP pairs with Run your job search now. Each tile prints two lines, a name and a subtitle that restates what Enter does in the reader's words. SWEEP SETTINGS reads Ranking, cards, tracking. SWEEPY'S TOOLBOX reads Edit profile, logs, help. EXIT SWEEPY reads Save changes and close, which promises to keep your work.
The action tiles lead with a verb and its object. The others label a place or an exit. A subtitle glosses any internal term in plain language. The two-digit numbers identify each tile rather than order the grid. The top row pairs 01 with 04. A tile joins the grid without renumbering the others. Navigation runs on the arrow keys and Enter.
Format hints inside the prompt
A prompt keeps the question on one line and, when the format matters, puts the rule beneath it, indented:
What job titles are you looking for?
(Separate multiple titles with a comma)
The salary prompt states the skip option inside the question:
What is your minimum target salary? (Leave blank to skip):
The rule appears on the line where the decision happens. The reader stays on screen. A terminal has no tooltip to fall back on.
Edit an answer without rerunning the wizard
The wizard runs fifteen steps, and Esc walks back one question at a time. The review screen lists eleven entries: ← Back, then Submit profile, then nine actions. Edit an answer sits directly under Submit profile. Revision sits one row away from submitting. A reader who wants to change an answer doesn't rerun every prompt.
Stage labels for the five steps
A command-line run stamps five numbered stages, each one stating the work.
[1/5] Loading profile...
[2/5] Discovering roles...
[3/5] Validating URLs...
[4/5] Scoring against resume...
[5/5] Generating reports...
The log lines state the stage number. The MCP progress payload names the item instead: step 1 of total 4 for the first of four job titles, labeled Discovering roles: Paralegal. Scoring roles reports the shortlist as the scorer works it. Readers see where the run sits and what remains. A progress bar would imply a duration the tool can't know.
The wait that returns a job id
A live sweep can run for a minute or longer. In MCP mode the tool call returns a running state instead of waiting for the whole sweep. That keeps the call inside a client's timeout and tells the caller that work continues.
run_sweep waits 45 seconds by default. wait_seconds sets that wait, clamped to 0 through 600, and SWEEPY_MCP_WAIT_SECONDS lowers the ceiling on hosts with tighter limits. The running state includes a job_id, a progress object, an elapsed_seconds value, and a message:
{
"status": "ok",
"sweep_status": "running",
"job_id": "<job id>",
"progress": { "step": 3, "total": 5, "label": "Validating URLs" },
"elapsed_seconds": 41.2,
"debug_log": "<path>",
"message": "The sweep is still running. Call get_sweep_status to wait for it, then continue with get_jobs."
}
The client polls get_sweep_status with the job_id until sweep_status reads "completed". Sweepy keeps working through the handoff regardless of whether the client stays connected. The copy has to fit inside the timeout and read correctly to a client that reconnects later. This is a running state that reports progress.
The 45 seconds is a product default, set by _DEFAULT_WAIT_SECONDS and capped by _MAX_WAIT_SECONDS. progress and elapsed_seconds change per run, as does debug_log. The message names the next tool call instead of restating numbers the caller already has.
Nowhere to hide weak copy
The interface relies on text alone, and the frame clips whatever runs long. A label has to be self-contained, because nothing else on screen explains it. Status messages state where the reader is, with no spinner to lean on.
The naming rule follows. START SWEEP, LOAD PROFILE, and BUILD PROFILE lead with the action. Their subtitles restate it as the reader's goal, so no one needs the internal idea of a "profile" to know what comes next. The score label applies the same rule to a number. KEYWORD OVERLAP marks the deterministic count, and MATCH marks an agent's judgment.
The frame width clips long strings
The terminal sets the terms. Text is the only layer that explains anything, and the frame clips whatever runs long. An error has to state the problem and the fix in the same string. The reader can't leave the line to read another one.
The strings pay for their own context. Could not parse salary %r. Enter a number like 65000, 65,000, or 65k. reports what failed and what to type instead, with %r replaced by the rejected entry. Current profile: none loaded / build one to start does the same for a missing profile. A GUI could put the second half of either sentence in a tooltip. Here the line includes both halves.
The label as the only explanation
The score label states who wrote the number. The docs put it plainly: "A MATCH card reflects judgment. A KEYWORD OVERLAP card reflects shared words." One label prints on a card beside one score. The reader knows which claim they have before opening the listing.
Each word also tells the reader what kind of comparison produced the figure. KEYWORD OVERLAP reports on two documents. MATCH reports on a person and a job. A reader who expects the two numbers to line up misreads one of them.
The label tracks the writer, not the interface. An agent can submit a judgment without a percentage. That card still reads KEYWORD OVERLAP, because the sweep wrote that number. The execution path lives outside the card. The report filename marks an MCP run with mcp, and the log header prints the execution method.
Tile naming follows the same rule. BUILD PROFILE states the action, and its subtitle, Set up your job search, drops the internal term for the reader's goal. LOAD PROFILE says Open a search you saved, which describes what the tile does.
What I wrote and how I checked it
Role: sole writer of the product strings this case study quotes. Wrote the launchpad subtitles and the wizard prompts, then the progress messaging and the validation copy. The score-provenance labels and the MCP handoff message that a client relays came last. Directed the build with Copilot and Gemini, under repository-level agent guidelines and a CI quality gate. Verified the literal product strings against the Sweepy source.
Calibrate trust, then act
A reader should calibrate trust before acting on a score and tell what the system is doing while they wait. The interface can't explain how Sweepy produced a number or how long a process takes. The label and status strings explain it in the fewest words, in a form that works without visual affordances.
The fifteen prompts in order
The wizard runs fifteen steps. The fifteen top-level prompts appear in order, and the yes-or-no questions render as a yes/no selector.
? What is your name?
>
? What job titles are you looking for?
(Separate multiple titles with a comma)
>
? Where do you want to work? (City, State):
>
? Do you want to see remote-only roles? (Y/n)
? Do you want to include hybrid roles? (Y/n)
? What is the path to your resume PDF?
>
? What is your minimum target salary? (Leave blank to skip):
>
? Which boards do you want to search? Pick from any engine; downloaded engines are labeled.
? Do you want to add custom platforms or ATS domains? (Y/n)
? Enter must-have skills or keywords to prioritize
(comma-separated, leave blank to extract from resume):
>
? What export formats do you want?
[x] PDF Report
[x] CSV Spreadsheet
[ ] JSON Data
? Add job-tracking columns to the CSV? (date applied, status, interview stage,
offer, follow-up date, contact, notes) (Y/n)
? Do you want to configure multiple resume tracks
(e.g. Tech Writer vs UX Writer)? (Y/n)
? Do you have a portfolio, writing samples, or case studies to submit
with applications? (Y/n)
? Enable debug logging? (Logs are saved under logs/ in the application
directory): (Y/n)