CommScore

View saved version →

---
name: review-a-communication
description: Review, proofread, score or improve an existing customer communication (an email, letter, text message, notice, web or app page, headline, tagline or other marketing copy, or policy wording) against a brand's voice with CommScore, then explain the result and offer fixes. Use whenever the user shares customer-facing text and asks whether it is clear, on brand, good enough or ready to send, asks you to proofread or check it, wants feedback, a score or a second opinion, or wants to compare or choose between versions, for their own organisation or any brand set up in their CommScore workspace, even if they don't mention CommScore.
---

# Review a communication

CommScore scores a communication against the organisation's own brand guide on five
pillars and names the specific things to fix. That gives the user consistent, evidence-based
feedback: the same checks every time, tied to their brand rather than to general taste.
Your job is to run the review, explain it in plain words and help the user act on it.

## 1. Find the brand

- If this conversation already has a brand_id, use it.
- Otherwise call `list_brands`.
  - One brand: use it.
  - Several brands: pick from context, such as the sender, signature, product or website
    in the text. If it's still unclear, ask one short question listing the brand names.

## 2. Score the text as it is

Score exactly what the user gave you. Don't tidy it up first, or the score describes your
version instead of theirs.

Call `score_text` with the text. Set `communication_type` from what it is (email, letter,
newsletter, invitation, text_message or document). Set `audience_rank` (1 = general public,
5 = specialists) and `action_expected` when they're clear from the text or the
conversation. Scoring takes up to a minute and uses the workspace's AI credits.

If the text is longer than the limit the tool reports, split it at natural sections and
score each one.

## 3. Report

Keep it short and concrete:

```
**<Brand>: 3.4 / 5 overall.** <headline from the result>

| Pillar | Score |
|---|---|
| Clarity | 3.5 |
| Certainty | 2.5 |
| Structure, style & grammar | 4.0 |
| Brand alignment | 3.5 |
| Customer experience | 3.5 |

**What to fix first**
1. **Certainty:** <finding, in plain words>. *"<evidence quoted from the text>"*.
   Try: <a concrete rewrite of that sentence>
2. ...
```

- Present scores as guidance, not pass/fail. They run from 1 to 5 (higher is better).
  Longer texts can vary by about a point between runs.
- Quote the evidence so the user can find the sentence.
- **Every fix ends with replacement wording the user can paste**, not just a description of
  the problem. For example, write *Try: "If you go over the limit, replies slow down until
  your next billing date."*, not "explain what happens at the limit". If the right wording
  depends on a fact you don't have, use a placeholder such as `[new limit]`.
- Review, don't rewrite: unless the user asked for a fixed version, give the fixes and
  offer the rewrite (step 4) rather than rewriting the whole text.
- Mention `reading_grade` when the audience is the general public: a lower grade is easier
  for more people to read.
- If `check_terminology` would add something (the brand has avoid terms and the text may
  use them), run it too. It is instant and free. List any avoided terms with their
  alternatives.

What the pillars mean, for explaining scores in plain words:

- **Clarity:** easy to understand at first read.
- **Certainty:** the reader knows what is happening, what to do and by when.
- **Structure, style & grammar:** well organised, correct and in house style.
- **Brand alignment:** sounds like the organisation and uses its words.
- **Customer experience:** how the message feels to the person receiving it.

## 4. Offer the fix

End by offering to fix it, e.g. "Want me to rewrite it with these fixes?" If the user says
yes:

1. Edit the text yourself, or call `rewrite_text` with `focus` set to `suggested_focus`.
2. Check that every fact, amount, date and legally required wording from the original
   survived, and that you added no new promises, deadlines or instructions the original
   didn't make. Use a placeholder or suggest them to the user instead.
3. Score the final text again with the original score's `draft.draft_id` as `draft_id`,
   and show before → after for the overall score and any pillar that moved (from
   `draft.change`), with the new text ready to copy. If you edit after that score, score
   again: the score you show must belong to the text you hand over.

## Comparing versions

When the user wants to compare drafts (theirs vs a colleague's, before vs after):

- Score each one with the same `communication_type`, `audience_rank` and
  `action_expected`, as separate drafts (no `draft_id`), each with a short `title` such
  as "Price notice A".
- Show the scores side by side.
- Say which fixes differ between the versions.
- Treat small overall differences as a tie. Look at whether the top fixes changed instead.

## Earlier scores

If the user asks how a communication improved, what they scored recently, or wants to
pick up a draft from an earlier conversation, call `get_score_history`. It is instant
and free, and shows only their own scores, including documents scored in the CommScore
Office add-in. To score a new version of one of their drafts, pass its id as `draft_id`.

## When something goes wrong

- **Access, licence or credit messages** from a tool: pass them on as written, because
  they say what the user or their admin can do. Offer your own read of the text, clearly
  labelled as not a CommScore score.
- **No brands in the workspace:** a CommScore admin needs to add one before CommScore can
  score text against it.

View saved version →

---
name: set-up-a-brand
description: Set up or update a brand's voice guide in CommScore (tone, values, style do's and don'ts, audiences, terms to use or avoid) from its website or from brand guidelines the user provides, so CommScore can write and score communications in that voice. Use whenever the user wants to add a brand or organisation to CommScore, build or fill in a brand voice guide, import brand guidelines or a style guide, or add terms the brand uses or avoids, even if they don't mention CommScore by name.
---

# Set up a brand

CommScore writes and scores communications against a brand's voice guide. A complete
guide makes everything else better: drafts sound like the organisation, and scores point at
what actually matters for it. This skill gets a brand from nothing (or half-filled) to a
guide the user has reviewed and approved.

The user stays in charge of what their brand guide says. Draft freely, but save only what
they have seen and agreed to.

## 1. Check what already exists

Call `list_brands`. If the brand is already there, don't create it again. Work on the
existing one: read it with `get_brand_profile` and fill the gaps (step 4). Brands with
the same name are told apart by website.

## 2. Create the brand (if it's new)

Call `create_brand` with the name, website, language (e.g. `en-AU`) and country (e.g.
`AU`). Ask the user for anything you can't infer. Creating a brand needs a CommScore admin
or member account; if the tool says so, tell the user who can do it.

If the user gave you brand guidelines (a pasted style guide, a document's text), you can
pass the parts you're confident about straight into `create_brand`, mapped to the guide
fields.

## 3. Draft the guide

There are two sources. Use whichever the user has, or both:

- **The website:** call `research_brand`. It drafts values, customer charter, tone,
  writing principles, style examples, audiences and terms from the brand's public web
  presence, in about 30 seconds, using the workspace's AI credits. It saves nothing.
  If part of it is unavailable, say which part and carry on with the rest.
- **Their own guidelines:** extract the guide fields from what they gave you. Quote their
  wording where you can; don't invent values or rules the document doesn't contain.

## 4. Review with the user, then save

Show the draft in readable sections, not as raw JSON:
- **Voice:** tone, core idea, writing principles.
- **Values:** company values, service values, customer charter.
- **Style:** do's, don'ts, checklist.
- **Audiences.**
- **Terms to use** and **terms to avoid**, each with its explanation or alternative.

Ask what to change. Apply their edits, then save:

- `update_brand_profile` fills empty fields and adds terms and audiences. It never
  overwrites, so it's safe for a first save or for topping up.
- If it reports `skipped` fields (already filled), show the user the current value next
  to the new one. Use `replace_brand_fields` only for the fields they confirm should be
  replaced. Remember that a list passed to it replaces the whole stored list.

## 5. Show the result

Call `get_brand_profile` and summarise what the guide now holds, in a few lines. Offer a
quick test: draft or score a short sample communication for the brand (an email or SMS)
so the user can see the guide at work.

## When something goes wrong

- **"Only CommScore admins and members can…":** the user's account can read brands but not
  change them. Suggest they ask a CommScore admin, or use the CommScore web app.
- **Web research turned off:** ask the user for their brand guidelines instead, and draft
  from those (step 3).
- **Duplicate refused by `create_brand`:** use the brand_id it gives you and continue from
  step 4.

View saved version →

---
name: write-on-brand
description: Write, edit or rewrite customer communications (emails, letters, text messages, push notifications, in-app messages, notices, replies to complaints, help-centre answers, web or app copy, headlines, social posts, policy wording) in a brand's voice using its brand guide in CommScore, and check the result with CommScore before handing it over. Use whenever the user asks you to draft, reply to, edit, rewrite or "make this sound like" a brand or organisation for its customers, members or the public, including any brand set up in their CommScore workspace, even if they don't mention CommScore.
---

# Write on brand

CommScore holds the organisation's brand voice and language guide (tone, style, audiences,
terms to use and avoid) and can score a draft against it. Read the guide before you write
and check the draft afterwards. The user then gets text that already sounds like their
organisation and has been checked, instead of a generic draft they have to fix.

## 1. Find the brand

- If this conversation already has a brand_id, use it.
- Otherwise call `list_brands`.
  - One brand: use it.
  - Several brands: pick from context, such as the organisation, product or website the
    user mentioned. If it's still unclear, ask one short question listing the brand names.
  - Brands with the same name: tell them apart by website. Don't guess.
  - No brands: tell the user a CommScore admin needs to add one first. You can still
    write the draft, but say it hasn't been checked against a brand guide.

## 2. Read the brand guide

Call `get_brand_profile`. Most of what matters for writing is in these fields:

- `preferred_tone`, `core_idea`, values and `customer_charter`: how the organisation wants
  to sound and what it promises customers.
- `style_do` / `style_dont` / `style_checklist`: concrete house-style rules. Follow them
  over your own default style.
- `audiences`: who the brand writes for. Match the reader of this communication.
- `approved_terms`: the brand's own words. Use them. For a general audience, add the
  `plain_explanation` the first time a term appears.
- `avoid_terms`: words the brand doesn't use. Use the alternative given.

## 3. Get the brief straight

Before drafting, be clear on:

- who is reading;
- what they need to know;
- what, if anything, they need to do, and how and by when.

Keep every fact the user gives exactly as given: amounts, dates (in the user's format),
names, reference numbers and any wording they say must stay. If a fact the reader needs is
missing (a date, an amount, a phone number), ask, or leave a clearly marked placeholder
such as `[due date]`. Never invent one. A confident draft with a made-up date is worse than
one with a visible gap.

The same goes for **promises and instructions**. Don't add a commitment the user didn't
make, such as "we'll update you by Friday", "you'll be refunded" or "we'll restore it".
Don't add instructions or warnings to the reader, such as "don't reset your account". A
warmer tone is your job; new obligations are the user's call. If one would help the reader,
suggest it to the user after the draft rather than putting it in.

## 4. Draft

Write the communication in the brand's voice, for the reader in step 3. Put what matters
most to the reader first. If the reader must act, say what to do, how and by when.

## 5. Check before handing over

1. Call `check_terminology` on the draft. It is instant and free. Swap any avoided terms
   it finds.
2. Call `score_text`. Set `communication_type` (email, letter, newsletter, invitation,
   text_message or document). Set `audience_rank` (1 = general public, 5 = specialists)
   and `action_expected` when you know them, because they change what good looks like.
   Scoring takes up to a minute and uses the workspace's AI credits.
   - Score anything that will go to customers.
   - For a quick throwaway line, the terminology check is usually enough.
3. If `top_fixes` point to real problems, fix them. Either:
   - edit the draft yourself, which often works well because you know the intent and the
     facts; or
   - call `rewrite_text` with `focus` set to `suggested_focus`, then check that the
     rewrite kept every fact from step 3.

   Then score once more, passing the first result's `draft.draft_id` as `draft_id`, so
   CommScore links the rounds and the result's `draft.change` shows what moved. Give the
   first score a short `title` (e.g. "Holiday closure email") so the user can find it in
   their history later.

**The score you report must belong to the text you hand over.** If you change the text
after the last score, even a small edit, score it again. If you can't (credits, errors),
say plainly that the score is for the earlier draft.

One improvement round is usually enough; two at most. Scores on longer texts can move by
about a point between runs, so don't spend the user's credits chasing a decimal. Stop when
the remaining fixes are minor or depend on something only the user knows.

## 6. Hand over

Lead with the finished communication, ready to copy. The user asked for the email, not a
report. After it, add a short CommScore note:

```
**CommScore:** 4.3 / 5 overall (first draft 3.6), brand: <brand name>
Clarity 4.5 · Certainty 4.0 · Structure, style & grammar 4.5 · Brand alignment 4.0 · Customer experience 4.5
Still open: <anything you couldn't fix, e.g. "add the actual due date">
```

Skip the "first draft" figure if you only scored once, and drop "Still open" if nothing is
open. If you scored more than once, show the trail from `draft.history`, e.g. `3.6 → 4.3`.

## When something goes wrong

- **Access, licence or credit messages** from a tool: pass the message on as written,
  because it says what the user or their admin can do. Then give the draft written from
  the brand guide, marked as not yet scored.
- **Text too long:** score it in sections and report each section.
- **Several drafts or variants requested** (e.g. an email and an SMS version): read the
  profile once, then write, check and score each variant.