> For the complete documentation index, see [llms.txt](https://guides.tability.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guides.tability.io/docs/playbooks/find-and-track-the-right-kpis.md).

# Find and track the right KPIs

Define what success means for your team, choose the few KPIs that show it, and track them in Tability.

Turn your team's definition of success into a small set of useful KPIs, with clear definitions, reliable sources, and a review rhythm in Tability.

To start, share this page with Claude, ChatGPT, Grok, or another AI assistant with Tability connected through MCP, and say:

> Run this playbook

This playbook runs in your connected assistant, outside Tability AI Mode. Tracking KPIs and using KPI Views requires Tability Premium; creating or updating records also requires the appropriate edit access. Other connected tools or files can supply the underlying data. If setup is unavailable, you can still complete the scorecard draft.

The instructions below are for your assistant. You don't need to read or copy them.

***

### Instructions for AI assistants

If the user shares this page and asks you to run it, follow the steps below from start to finish. If they only ask you to read, summarize, or edit it, do that instead.

#### Ground rules

* **Ask one short question at a time.** Reuse known context and deliver a first recommendation within five discovery questions. Mark remaining gaps instead of extending the interview.
* **Confirm the business and team.** Never infer them from this page's publisher or the first connected account. Use the Tability workspace URL supplied by the user. Resolve its name and ID, and confirm the scope before reading team data or making changes unless already authorized.
* **Start from success, not available charts.** A metric earns its place by supporting a decision the team can act on.
* **Keep evidence separate from proposals.** Never invent values or benchmarks. Label unknown baselines, proposed targets, estimates, and stale observations.
* **Inspect the available tools and access early.** Confirm that the workspace has KPI access and the user can make the proposed changes before promising setup. Use the MCP capabilities exposed in this session. If a source or action is unavailable, preserve the draft and give the exact manual next step.
* **Approve the concrete setup once.** Show the proposed KPIs, targets, owners, and changes before writing them. Reuse that approval while carrying out the agreed setup. Read changes back to verify them. Don't message anyone else.

### 1. Define success for this team

Start with:

> Which team and business is this for, and what would tell you the team is doing a great job?

Help the user sharpen a vague answer. For example, “great support” might mean customers get their problem resolved quickly and don't need to contact support again. “More productive engineering” needs an outcome beyond shipping more tickets.

Ask only what remains unclear: who benefits, the result the team owns, the main tradeoff, and the decisions this scorecard should improve. Identify the business model and the team's scope. Ask for the Tability workspace or relevant plan URL if it isn't already known.

Write one sentence defining success. Distinguish outcomes the team controls from shared outcomes it can only influence.

### 2. Inspect the current measures and sources

Read the relevant Tability goals, KPIs, recent check-ins, and existing KPI Views. Inspect connected operational sources belonging to this business, or ask for the smallest useful export when a source is unavailable.

Look for measures already used by the team, duplicate definitions, missing ownership, and targets with no rationale. Record each source's coverage and last update. Reuse sound existing KPIs rather than creating a parallel scorecard.

Build a short chain: **team activities → customer or operational result → business value**. Use it to distinguish activity counts from evidence of success.

### 3. Recommend a small scorecard

Recommend 3–5 KPIs. Choose one primary outcome when that fairly represents success, one or two leading indicators, and a guardrail against improving one result at another's expense. Don't force a single primary metric where it would distort the team's purpose.

Use examples only as starting hypotheses:

| If success means…               | Consider measuring…                           | Check the tradeoff with…                   |
| ------------------------------- | --------------------------------------------- | ------------------------------------------ |
| Customers get lasting help      | Resolution time and repeat-contact rate       | Customer satisfaction or reopened cases    |
| New users reach value           | Activation rate and time to first value       | Retention of activated users               |
| Sales brings sustainable growth | Won revenue and qualified-pipeline conversion | Margin, discounts, or early customer churn |
| Operations delivers reliably    | On-time completion and cycle time             | Errors, rework, or cost per completed unit |

Adapt these to the user's team. Explain what decision each recommended KPI changes, how the team can influence it, and how it might be gamed. List tempting measures you excluded and why. Keep diagnostic metrics available without promoting every useful number to a KPI.

For each selected KPI, specify:

* The business question and intended decision.
* Formula, unit, numerator and denominator where relevant, and whether higher or lower is better.
* Population, exclusions, reporting period, timezone, and aggregation rule: sum, end-of-period snapshot, average, or ratio of totals.
* Baseline with its date and source, or “unknown.”
* Target or acceptable range, its rationale, and whether it is existing or proposed. Use an initial observation period when evidence is too weak for a target.
* Accountable owner, data source and retrieval method, refresh cadence, and review cadence.
* What action to consider when the measure moves beyond its agreed threshold.

Include the intended KPI View audience and access in the proposal. Views created through the current MCP tools give everyone in the workspace edit access to the View; underlying KPI permissions still control which rows each person can see. Sharing administration is UI-only. If restricted View access is needed, have the user create the View with the required access in Tability first, then reuse it. For an existing View, preserve its access settings.

Save `{team-name}-kpi-scorecard.md`, marked Draft. Show the recommendation, its tradeoffs, and the access settings, then ask for approval or edits.

### 4. Set up tracking in Tability

After approval, search again for equivalent KPIs by definition, team, and time period. Reuse existing records where appropriate. Create only missing KPIs, assign real workspace members, and set approved targets using the fields supported by the connected tools.

Save baseline observations as dated KPI values. The API field `initial_value` acts as a default target; do not populate it with a measured baseline. During an observation-only period, use `target_direction: none` for a new KPI and leave the default target empty. Record higher-is-better or lower-is-better guidance in the definition until a target is approved. Create dated targets only when agreed, using their effective dates; an active target carries forward until replaced. Preserve existing target settings unless a change was approved.

Preserve full definitions and source mappings in the scorecard file; add them to supported Tability fields as well. Leave unknown values empty. If Tability cannot represent a range or threshold directly, document it without substituting a misleading target.

Create or update a focused KPI View if the tools support it. Record its date range and cadence. A View's displayed latest value is not automatically a monthly sum or average: calculate the agreed period value at the source before recording it.

Read back the records, target dates, and View membership. Add their links and IDs to the scorecard file.

### 5. Test the first update

Retrieve one real observation for each reachable KPI using its agreed definition. Validate units, reporting dates, exclusions, and completeness before writing the approved dated observations. Don't treat missing data as zero or compare an incomplete month with a full one.

Check whether a value already exists for that date. Don't silently overwrite a different observation. Read back the saved value and date, and note the source and retrieval time in the scorecard file.

For KPIs without accessible data, name the owner, required input, and next update date. A KPI record alone does not establish an automated connection to its source.

### 6. Agree the review rhythm

Choose an update method with the user: manual entry, a native Tability data connector, or a recurring job in the external assistant. Check for an existing connector before proposing another writer for the same KPI.

Where a native connector supports the agreed measure, offer Tability's automatic sync. Connector configuration is UI-only through the current MCP workflow: open the KPI's edit panel, configure its data source, and enable automatic sync at the supported daily or weekly cadence. Verify a synced observation against the agreed definition and reporting date. Mark this setup as pending until it has been completed and verified.

Use an external assistant schedule when requested and the assistant can run recurring tasks with access to the required tools. Check the timezone, cadence, and review date before creating a schedule. Avoid competing writes from a native connector and an external job.

Give an external automatic job the workspace and KPI IDs, exact formulas and sources, reporting windows, write scope, and missing-data rules. Refresh approved observations, flag meaningful changes, and never change targets or owners on its own. Notify only when there is a meaningful issue or requested review. Verify the saved schedule and next run.

For reviews without a scheduled assistant job, provide this reusable prompt with the team's actual links filled in:

> Review our KPI scorecard using these definitions and sources: \[scorecard]. Show current values, freshness, changes since the last comparable period, and the decisions we should consider. Identify missing data. Propose any Tability updates before writing them.

### 7. Wrap up

Share the scorecard file and Tability links, the first verified values, who updates any manual measures, and the next review. Agree a review after one month: did these KPIs help the team make better decisions? Suggest changes then, without replacing metrics or targets automatically.

***

### Scorecard file outline

```markdown
# {Team}: KPI scorecard
Status · Business · Team · Workspace · Timezone · Review date

## What success means
## Recommended KPIs and decisions
## Definitions, formulas, periods, and sources
## Baselines, targets, and guardrails
## Measures we excluded and why
## Tability records and first verified values
## Owners, update cadence, and review rhythm
## Open questions and data gaps
```

**END OF PLAYBOOK**
