> ## Documentation Index
> Fetch the complete documentation index at: https://docs.botbrains.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Scorecards

> Score conversations from 0 to 100 with weighted points over their conversation attributes

export const feature_0 = "scorecards"

export const note_0 = undefined

<Warning>
  [ServiceLens](/concepts/servicelens), which includes {feature_0}, is currently in beta and available per project. Contact [support@botbrains.io](mailto:support@botbrains.io) to turn it on for your project. {note_0}
</Warning>

A scorecard combines several [conversation attributes](/concepts/conversation-attributes) into one score from 0 to 100. You pick the attributes, decide how many points each value earns, and set how much each item counts. botBrains updates the score automatically whenever one of the underlying values changes. Use scores to filter conversations, flag low scorers with [monitors](/concepts/monitors), and let people answer the items only they can judge in a [review queue](/concepts/review-queue).

## How Scorecards Work

A scorecard is an attribute of type Scorecard with 1 to 50 items. Each item scores one attribute:

| Setting | What it does |
| - | - |
| **Attribute** | The attribute to score: a Yes / No, Single select, Integer, or Decimal attribute, or one of the built-ins Status, Topic, and CSAT Rating. Each attribute can appear once. Multi select, text, date, and scorecard attributes can't be items. |
| **Points** | 0 to 100 points per value. A value without points shows as N/A and doesn't count. |
| **Weight** | 0 to 100. The editor shows the share of the score each item gets. |
| **Critical** | If a critical item scores 0 points, the whole scorecard scores 0, whatever its weight. |

The score is the weighted average of the items that earned points. botBrains multiplies each item's points by its weight, adds the results, and divides by the sum of those items' weights. Items with weight 0, values without points, and empty values drop out, so they don't pull the score down. [Unanswered items](#unanswered-items) are the exception: they hold the score back. If no weighted item earned points, the conversation has no score.

| Item | Value | Points | Weight |
| - | - | - | - |
| Issue resolved (Yes / No) | Yes | 100 | 2 |
| Tone (Single select) | Neutral | 50 | 1 |
| Refund policy followed (Yes / No, critical) | Yes | 100 | 1 |

This conversation scores (100 × 2 + 50 × 1 + 100 × 1) / 4 = 87.5. If the refund policy item were No at 0 points, the conversation would score 0 because the item is critical.

### Points for Numbers

For Integer and Decimal attributes, you give points to anchor values and botBrains interpolates linearly between them. A value outside the anchors gets the points of the nearest anchor. For example, with CSAT Rating anchors 1 = 0 points and 5 = 100 points, a rating of 4 earns 75 points.

### Unanswered Items

A manual item is a scorecard item whose attribute uses the fill mode **Manual**. While a manual item has no value, or a critical item has no value because the AI couldn't determine one, the scorecard has no score and the details panel shows **Awaiting review** instead. Score filters and monitor thresholds leave the conversation out until then. An active monitor whose scorecard has a manual item works as a [review queue](/concepts/review-queue), where people answer the missing items.

**What counts as an answer.** A person sets the value or clears it, for example with **N/A** in a review queue. The AI answers when it fills the value or decides that no option applies.

**Critical AI items.** A critical item the AI fills holds the score back only when the AI couldn't determine a value for a conversation in the attribute's selection. A person then has to answer it.

**Critical failures.** A critical item at 0 points sets the score to 0 right away, even while other items wait for an answer.

**Built-in attributes.** Built-in attributes never hold the score back. A conversation without a rating skips that item.

**Existing scores.** A manual item holds back the score of every conversation. Adding one to a scorecard that's already in use, or switching an item's attribute to **Manual**, removes the score from all conversations until someone answers.

## Creating a Scorecard

Click **New scorecard** on the [conversation attributes page](https://platform.botbrains.io/~/conversation-attributes), or open the [scorecard editor](https://platform.botbrains.io/~/conversation-attributes?edit_attribute_id=~\&type=scorecard) directly. Add items, pick an attribute for each, and set its points, weight, and critical switch. New items start with weight 1, and Yes / No items start with Yes = 100 and No = 0. Each item needs at least one value with points, and at least one item needs a weight of 1 or more.

<img src="https://mintlify.s3.us-west-1.amazonaws.com/botbrains/images/scorecards/scorecard-editor.png" alt="Scorecard editor showing three items, each with an attribute picker, a weight input and slider with its share of the score, a Critical switch, and points per value" data-generation-prompt="Navigate to platform.botbrains.io/~/conversation-attributes in a project with ServiceLens turned on and open a scorecard from the Scorecards group that has three items: a Yes / No attribute with weight 2, a Single select attribute with weight 1 and one option left empty (N/A), and the CSAT Rating built-in with weight 1 and the Critical switch on. Scroll the sheet to the Items section and capture all three items, including each Weight input, slider and '% of the score' text, the Critical switches and the points per value. Use a 1920x1080 viewport, collapse the sidebar, and crop to the sheet." />

A new scorecard scores a conversation the next time one of the [changes below](#when-scores-update) happens to it. To score existing conversations, click **Recompute** on the scorecard. You can't delete an attribute while a scorecard uses it, or a scorecard while a monitor uses it.

## When Scores Update

botBrains recalculates scores after each of these changes:

| Change | What botBrains recalculates |
| - | - |
| The AI fills or updates a conversation's attributes | That conversation's scorecards |
| A person sets or clears an attribute value | That conversation's scorecards |
| A conversation's status, topic, or rating changes | That conversation's scorecards |
| You edit a scorecard's items, or the options of an attribute it uses | The scorecard on every conversation in the project |
| You click **Recompute** on a scorecard | Up to 10,000 of the newest conversations in a date range (last 30 days by default) |

## CX Score

The CX Score is a ready-made scorecard that estimates the customer experience. Install it from the [conversation attributes page](https://platform.botbrains.io/~/conversation-attributes) by clicking **New attribute** and choosing **CX Score** under **Templates**. It adds six AI signals with equal weight, such as customer effort and AI agent quality, which the AI fills after conversations with at least two customer messages. You can rename the CX Score, but you can't change its items or points. Installing it doesn't score past conversations; backfill the signals to score them.

## Using Scores

**Details panel.** The **Scorecards** section of a conversation's details panel shows each score as a pill: red below 50, amber below 75, and green from 75. A dash means the conversation has no score. Click the pill to see each item's value, points, and weight, with critical items marked.

<img src="https://mintlify.s3.us-west-1.amazonaws.com/botbrains/images/scorecards/score-breakdown.png" alt="Score pill in the conversation details panel with its popover open, listing each item with its value, points and weight" data-generation-prompt="Use a project with ServiceLens turned on and the CX Score template installed. Navigate to platform.botbrains.io/~/conversations and open a conversation that has a CX Score (pick one where at least one signal is Neutral so its Points column shows N/A). In the right details panel, find the Scorecards section and click the colored score pill to open its popover. Capture the popover with the scorecard label, the score, and the Item, Points and Weight table. Use a 1920x1080 viewport and crop to the details panel and popover." />

**Conversation filters.** Filter the [conversation list](https://platform.botbrains.io/~/conversations) by a score range with the scorecard's Min and Max fields. The URL keeps the filter, so you can share the filtered view. To build such links yourself, see [Filter by Attributes](/concepts/conversation-attributes#filter-by-attributes).

**Monitors.** Flag conversations that score below a threshold or fail a critical item. See [Flag Criteria](/concepts/monitors#flag-criteria).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.