untool.ai — voice & tone¶
The voice is the same on a landing page, in an error message, and in a release note: calm, precise, useful. Tone shifts (urgency, sympathy, celebration-when-truly-earned) live on a small axis. The voice does not move.
This guide is operational: it tells you what to write and what to remove. The
philosophy lives in UNTOOL.md.
1. The four rules¶
- Tell the truth, including unflattering truths. If a request took longer than it should, say so. If a feature is in preview, say so.
- Earn every word. Cut every word the sentence works without. Then cut one more.
- Verbs over nouns. "Search sources," not "Source search." Action is information.
- Adults talking to adults. No exclamation marks. No "awesome." No "magic." No "boom."
2. Headlines¶
- Sentence case. "Search across every source," not "Search Across Every Source."
- Six words or fewer, where possible. The headline is a question or a promise; not both.
- No period at the end. Display type is not punctuated.
- Numbers in numerals when they carry information. "3 sources indexed," not "Three sources indexed."
| Good | Bad |
|---|---|
| Search across every source | Powerful Universal Search Across All Your Stuff! |
| 3 sources still ingesting | We're Working Hard on Your Files |
| The model is between calls | AI is thinking... |
3. Body copy¶
- Sentences are short. A sentence with three commas is two sentences.
- One idea per paragraph. Two paragraphs is two ideas.
- No "we are excited to." State the thing.
- No "simply" or "just." They lie about difficulty.
- Lists are parallel. All start with a verb, or all are nouns; not both.
4. Buttons and controls¶
- Verbs. "Delete source," not "Confirm."
- Specific objects. "Delete
pricing.pdf," not "Delete file." - Two-word max for primary action labels.
- Cancel is always "Cancel." Not "Nevermind," not "Take me back."
| Good | Bad |
|---|---|
| Search | Run search |
| Delete source | OK |
| Sign in | Get started |
| Save changes | Submit |
5. Errors¶
The error message is a contract with the user. It has three parts in this order:
- What happened. In plain English. Not a stack trace, not a code.
- Why it matters. What this means for the user's task.
- What they can do. A button, a link, or "try again in a few seconds."
| Good | Bad |
|---|---|
| Couldn't reach the search index. Your sources are safe. Try again in a moment. | Error 503: Service Unavailable |
pricing.pdf is encrypted. Open it in a PDF reader, save an unencrypted copy, and re-upload. |
Failed to ingest file |
| You signed out in another tab. Sign in to keep going. | Unauthorized |
If you do not know what the user can do, say so honestly: "We're looking into it. You don't need to do anything." Better than a fake instruction.
6. Empty states¶
Empty states are not motivational posters. They explain:
- Why the screen is empty (no sources yet, no results, etc.).
- The one most useful next action.
- (Optional, one line) A pointer to a deeper guide.
No illustrations of cartoon astronauts. No "Wow, such empty." No exclamation points.
7. Loading and progress¶
- Show structure, not spinners. A skeleton of the page that's about to appear beats a spinner every time.
- Show progress, not promises. "Indexing 3 of 11 sources" beats "Working hard on your stuff."
- Be honest about indeterminate work. If you don't know the ETA, say "this can take up to a minute." Do not invent a percentage.
8. Tone, on a single axis¶
The voice is constant. The tone moves on one axis: from measured to urgent. We do not need a third dimension.
| Tone | When | Example |
|---|---|---|
| Measured | Routine work. Most of the product, most of the time. | "3 sources indexed. 11 chunks ready to search." |
| Engaged | A choice with consequence. A nudge. An onboarding step. | "You can search 11 sources now. Add more anytime." |
| Urgent | Destructive actions. Errors. Time-bound things. | "This will delete pricing.pdf and 318 chunks. You have 30 seconds to undo." |
We never go above urgent. There is no "frantic." There is no "celebratory."
9. Numbers and units¶
- Numerals always win in data. Even one, two, three. "1 source," not "one source."
- Units are present. "42 ms," not "42." "$3.20," not "3.20."
- Tabular numbers in tables.
font-variant-numeric: tabular-nums;is on by default in<Numeric>. - Locale-aware formatting.
Intl.NumberFormatfor thousands separators, always.
10. The micro-rules¶
Small but enforced.
- "Sign in" / "Sign out" (two words). Not "log in."
- "Email" not "e-mail."
- "Webhook" one word.
- "Open-source" hyphenated as adjective; "open source" as noun.
- "Untool" capitalized at the start of sentences; otherwise lowercase to
match the mark.
untool.aiis never typeset in caps. - Oxford comma. American English. No semicolons in product copy (they belong in docs).
- Ellipsis is
…, not.... Em dash is—, not--.
11. Voice exemplars¶
Three reference passages we can point to.
Release note (measured):
The cockpit's recent-commands list now wraps long queries instead of truncating them. If a query no longer fits on one row, you'll see all of it. Filed by Jamie.
Empty state (measured):
No sources yet. Add a PDF or paste a URL to begin indexing. [Add a source]
Destructive confirmation (urgent):
Delete
pricing.pdf? This removes 318 indexed chunks. You can undo this for 30 seconds. [Delete source] [Cancel]
If the copy you are writing fits in this register, it belongs. If not, it needs another pass.