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

# MCP Actions

> Reference for all Soundcheck MCP actions available through the Actions Registry.

Soundcheck exposes 42 MCP actions through the Actions Registry, enabling AI agents to read and manage checks, tracks, campaigns, exemptions, facts, and compliance analytics.

Actions are grouped below by domain. Each entry lists the action name, what it does, its input parameters, and its return type.

## Checks

### `create-check`

Creates a new check definition in Soundcheck.

**Attributes:** `readOnly: false` · `idempotent: false`

**Parameters**

| Name                   | Type                                      | Required | Description                                                |
| ---------------------- | ----------------------------------------- | -------- | ---------------------------------------------------------- |
| `id`                   | `string`                                  | Yes      | Unique check identifier (slug-style, e.g. `has-readme`)    |
| `name`                 | `string`                                  | Yes      | Display name (max 100 characters)                          |
| `description`          | `string`                                  | Yes      | Human-readable description of the check                    |
| `ownerEntityRef`       | `string`                                  | Yes      | Backstage entity ref of the owner                          |
| `type`                 | `'manual' \| 'default'`                   | No       | Check type (default: `'default'`)                          |
| `rule`                 | `NestedConditionSchema`                   | No       | Rule to evaluate; required for `default` checks            |
| `applicable`           | `NestedConditionSchema`                   | No       | Applicability rule                                         |
| `pathResolver`         | `string`                                  | No       | Custom path resolver (default: `jsonpath`)                 |
| `includeFilter`        | `Filter` (~~`CatalogFilter`~~ deprecated) | No       | Entity inclusion filter                                    |
| `excludeFilter`        | `Filter`                                  | No       | Entity exclusion filter (requires `includeFilter`)         |
| `warning`              | `boolean`                                 | No       | If `true`, failures emit a warning state instead of failed |
| `passedMessage`        | `string`                                  | No       | Message shown when the check passes                        |
| `failedMessage`        | `string`                                  | No       | Message shown when the check fails                         |
| `notApplicableMessage` | `string`                                  | No       | Message shown when the check is not applicable             |
| `supportChannel`       | `string`                                  | No       | Support channel (Slack, email, etc.)                       |
| `schedule`             | `Schedule`                                | No       | Execution schedule                                         |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{ "checkId": "string" }
```

***

### `update-check`

Updates an existing check definition. Only provided fields are changed.

**Attributes:** `readOnly: false` · `idempotent: true`

**Parameters**

| Name                   | Type                                              | Required | Description                                       |
| ---------------------- | ------------------------------------------------- | -------- | ------------------------------------------------- |
| `checkId`              | `string`                                          | Yes      | ID of the check to update                         |
| `name`                 | `string`                                          | No       | Display name (max 100 characters)                 |
| `description`          | `string`                                          | No       | Check description                                 |
| `ownerEntityRef`       | `string`                                          | No       | Backstage entity ref of the owner                 |
| `type`                 | `'manual' \| 'default'`                           | No       | Check type                                        |
| `rule`                 | `NestedConditionSchema \| null`                   | No       | Rule to evaluate; pass `null` to clear            |
| `applicable`           | `NestedConditionSchema \| null`                   | No       | Applicability rule; pass `null` to clear          |
| `pathResolver`         | `string \| null`                                  | No       | Custom path resolver; pass `null` to clear        |
| `includeFilter`        | `Filter \| null` (~~`CatalogFilter`~~ deprecated) | No       | Entity inclusion filter; pass `null` to clear     |
| `excludeFilter`        | `Filter \| null`                                  | No       | Entity exclusion filter; pass `null` to clear     |
| `warning`              | `boolean`                                         | No       | If `true`, failures emit a warning state          |
| `passedMessage`        | `string \| null`                                  | No       | Message on pass; pass `null` to clear             |
| `failedMessage`        | `string \| null`                                  | No       | Message on failure; pass `null` to clear          |
| `notApplicableMessage` | `string \| null`                                  | No       | Message when not applicable; pass `null` to clear |
| `supportChannel`       | `string \| null`                                  | No       | Support channel; pass `null` to clear             |
| `schedule`             | `Schedule \| null`                                | No       | Execution schedule; pass `null` to clear          |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{ "checkId": "string" }
```

***

### `delete-check`

Permanently deletes a check definition. Fails if the check is still referenced by active (non-draft) tracks.

**Attributes:** `readOnly: false` · `idempotent: false`

**Parameters**

| Name      | Type     | Required | Description               |
| --------- | -------- | -------- | ------------------------- |
| `checkId` | `string` | Yes      | ID of the check to delete |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{ "checkId": "string", "deleted": true }
```

***

### `list-checks`

Returns all registered Soundcheck checks.

**Attributes:** `readOnly: true` · `idempotent: true`

**Parameters:** None

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "checks": [{ "id": "string", "name": "string", "description": "string" }]
}
```

***

### `get-check-definition`

Returns what a check evaluates: rule type, fact collectors, pass criteria, and pass/fail messages.

**Attributes:** `readOnly: true` · `idempotent: true`

**Parameters**

| Name      | Type     | Required | Description     |
| --------- | -------- | -------- | --------------- |
| `checkId` | `string` | Yes      | ID of the check |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "id": "string",
  "name": "string",
  "description": "string",
  "type": "manual | default",
  "factCollectors": ["string"],
  "rule": {},
  "filter": {},
  "passMessage": "string",
  "failMessage": "string",
  "supportChannel": "string"
}
```

***

### `get-check-details`

Returns the full details of a check, including pass/fail counts and the tracks that reference it.

**Attributes:** `readOnly: true` · `idempotent: true`

**Parameters**

| Name      | Type     | Required | Description     |
| --------- | -------- | -------- | --------------- |
| `checkId` | `string` | Yes      | ID of the check |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "id": "string",
  "name": "string",
  "description": "string",
  "ownerEntityRef": "string",
  "rule": {},
  "filter": {},
  "passedMessage": "string",
  "failedMessage": "string",
  "passingCount": 0,
  "failingCount": 0,
  "associatedTracks": [{ "id": "string", "name": "string" }]
}
```

***

### `execute-check`

Triggers a check to run on a component and persists the result. Manual-type checks cannot be executed; use `set-manual-check-result` instead.

**Attributes:** `readOnly: false` · `idempotent: false`

**Parameters**

| Name        | Type     | Required | Description                                            |
| ----------- | -------- | -------- | ------------------------------------------------------ |
| `checkId`   | `string` | Yes      | ID of the check to execute                             |
| `entityRef` | `string` | Yes      | Entity reference (e.g. `component:default/my-service`) |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "checkId": "string",
  "entityRef": "string",
  "state": "string",
  "timestamp": "string"
}
```

***

### `set-manual-check-result`

Sets the pass/fail result for a manual-type check on a component, with a justification.

**Attributes:** `readOnly: false` · `idempotent: true`

**Parameters**

| Name            | Type                   | Required | Description                                            |
| --------------- | ---------------------- | -------- | ------------------------------------------------------ |
| `checkId`       | `string`               | Yes      | ID of the manual check                                 |
| `entityRef`     | `string`               | Yes      | Entity reference (e.g. `component:default/my-service`) |
| `state`         | `'passed' \| 'failed'` | Yes      | Result state to set                                    |
| `justification` | `string`               | Yes      | Reason for this result                                 |
| `submittedBy`   | `string`               | Yes      | User reference (e.g. `user:default/jsmith`)            |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "checkId": "string",
  "entityRef": "string",
  "state": "passed | failed",
  "justification": "string",
  "timestamp": "string"
}
```

***

### `get-check-failure-details`

Returns exactly why a check is failing for a component: actual value, expected value, fact data, and failure reason.

**Attributes:** `readOnly: true` · `idempotent: true`

**Parameters**

| Name        | Type     | Required | Description      |
| ----------- | -------- | -------- | ---------------- |
| `checkId`   | `string` | Yes      | ID of the check  |
| `entityRef` | `string` | Yes      | Entity reference |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "status": "string",
  "actualValue": null,
  "expectedValue": null,
  "failureReason": "string",
  "lastRunAt": "string",
  "checkRule": {},
  "factData": null
}
```

***

### `get-check-history`

Returns the last 30 days of pass/fail history for a check on a given entity, along with a trend indicator.

**Attributes:** `readOnly: true` · `idempotent: true`

**Parameters**

| Name        | Type     | Required | Description      |
| ----------- | -------- | -------- | ---------------- |
| `checkId`   | `string` | Yes      | ID of the check  |
| `entityRef` | `string` | Yes      | Entity reference |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "history": [{ "date": "YYYY-MM-DD", "state": "string" }],
  "trend": "improving | declining | stable"
}
```

***

### `search-checks`

Searches for checks by keyword, returning matching checks with descriptions and associated tracks.

**Attributes:** `readOnly: true` · `idempotent: true`

**Parameters**

| Name    | Type     | Required | Description                                               |
| ------- | -------- | -------- | --------------------------------------------------------- |
| `query` | `string` | Yes      | Search term to match against check names and descriptions |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "checks": [
    {
      "checkId": "string",
      "checkName": "string",
      "description": "string",
      "associatedTracks": [{ "id": "string", "name": "string" }]
    }
  ]
}
```

***

## Tracks

### `create-track`

Creates a new compliance track with specified checks and levels.

**Attributes:** `readOnly: false` · `idempotent: false`

**Parameters**

| Name               | Type                                      | Required | Description                                            |
| ------------------ | ----------------------------------------- | -------- | ------------------------------------------------------ |
| `id`               | `string`                                  | Yes      | Unique track identifier (slug-style)                   |
| `name`             | `string`                                  | Yes      | Display name (max 100 characters)                      |
| `description`      | `string`                                  | Yes      | Track description (supports Markdown)                  |
| `ownerEntityRef`   | `string`                                  | Yes      | Backstage entity ref of the owner                      |
| `levels`           | `array`                                   | Yes      | Ordered levels, each containing check IDs              |
| `documentationURL` | `string`                                  | No       | Optional documentation link                            |
| `badgeType`        | `'medal' \| 'status'`                     | No       | Badge type (default: `'status'`)                       |
| `draft`            | `boolean`                                 | No       | Whether the track starts as a draft (default: `false`) |
| `filter`           | `Filter` (~~`CatalogFilter`~~ deprecated) | No       | Entity inclusion filter                                |
| `exclude`          | `Filter`                                  | No       | Entity exclusion filter (requires `filter`)            |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "trackId": "string",
  "trackName": "string",
  "checksCount": 0,
  "levelsCount": 0
}
```

***

### `update-track`

Updates an existing track. Only provided fields are changed.

**Attributes:** `readOnly: false` · `idempotent: true`

**Parameters**

| Name               | Type                                              | Required | Description                                   |
| ------------------ | ------------------------------------------------- | -------- | --------------------------------------------- |
| `trackId`          | `string`                                          | Yes      | ID of the track to update                     |
| `name`             | `string`                                          | No       | Display name                                  |
| `description`      | `string`                                          | No       | Track description                             |
| `ownerEntityRef`   | `string`                                          | No       | Backstage entity ref of the owner             |
| `documentationURL` | `string \| null`                                  | No       | Documentation link; pass `null` to clear      |
| `badgeType`        | `'medal' \| 'status' \| null`                     | No       | Badge type; pass `null` to clear              |
| `draft`            | `boolean`                                         | No       | Draft state                                   |
| `levels`           | `array`                                           | No       | Replaces all existing levels                  |
| `includeFilter`    | `Filter \| null` (~~`CatalogFilter`~~ deprecated) | No       | Entity inclusion filter; pass `null` to clear |
| `excludeFilter`    | `Filter \| null`                                  | No       | Entity exclusion filter; pass `null` to clear |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "trackId": "string",
  "trackName": "string",
  "checksCount": 0,
  "levelsCount": 0
}
```

***

### `delete-track`

Permanently deletes a track. Fails if still referenced by active (non-archived) campaigns.

**Attributes:** `readOnly: false` · `idempotent: false`

**Parameters**

| Name      | Type     | Required | Description               |
| --------- | -------- | -------- | ------------------------- |
| `trackId` | `string` | Yes      | ID of the track to delete |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{ "trackId": "string", "deleted": true }
```

***

### `list-tracks`

Returns all registered Soundcheck tracks with their IDs, names, and level names.

**Attributes:** `readOnly: true` · `idempotent: true`

**Parameters:** None

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "tracks": [
    {
      "id": "string",
      "name": "string",
      "levels": [{ "ordinal": 0, "name": "string" }]
    }
  ]
}
```

***

### `get-track-details`

Returns the full configuration of a track: name, description, owner, levels with check IDs, and entity filter.

**Attributes:** `readOnly: true` · `idempotent: true`

**Parameters**

| Name      | Type     | Required | Description     |
| --------- | -------- | -------- | --------------- |
| `trackId` | `string` | Yes      | ID of the track |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "id": "string",
  "name": "string",
  "description": "string",
  "owner": "string",
  "filter": {},
  "levels": [{ "ordinal": 0, "name": "string", "checkIds": ["string"] }]
}
```

***

### `get-track-stats`

Returns adoption metrics for a track: component counts and percentage at each compliance level.

**Attributes:** `readOnly: true` · `idempotent: true`

**Parameters**

| Name      | Type     | Required | Description     |
| --------- | -------- | -------- | --------------- |
| `trackId` | `string` | Yes      | ID of the track |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "trackId": "string",
  "trackName": "string",
  "totalComponents": 0,
  "levelBreakdown": [{ "level": "string", "count": 0, "percentage": 0 }]
}
```

***

### `list-track-blockers`

Returns the most common failing checks in a track, with failure counts and the percentage of components failing each check.

**Attributes:** `readOnly: true` · `idempotent: true`

**Parameters**

| Name      | Type     | Required | Description                                          |
| --------- | -------- | -------- | ---------------------------------------------------- |
| `trackId` | `string` | Yes      | ID of the track                                      |
| `limit`   | `number` | No       | Maximum number of blockers to return (default: `10`) |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "blockers": [
    {
      "checkId": "string",
      "checkName": "string",
      "failingCount": 0,
      "totalCount": 0,
      "failurePercentage": 0
    }
  ]
}
```

***

## Campaigns

### `create-campaign`

Creates a new compliance campaign with a track, milestones, and entity filters.

**Attributes:** `readOnly: false` · `idempotent: false`

**Parameters**

| Name             | Type                                      | Required | Description                                      |
| ---------------- | ----------------------------------------- | -------- | ------------------------------------------------ |
| `id`             | `string`                                  | Yes      | Unique campaign identifier (slug-style)          |
| `name`           | `string`                                  | Yes      | Campaign display name                            |
| `description`    | `string`                                  | Yes      | Campaign description (supports Markdown)         |
| `ownerEntityRef` | `string`                                  | Yes      | Backstage entity ref of the campaign owner       |
| `startDate`      | `string`                                  | Yes      | Campaign start date (ISO 8601)                   |
| `endDate`        | `string`                                  | Yes      | Campaign end date (ISO 8601)                     |
| `checkIds`       | `string[]`                                | Yes      | Check IDs for the campaign (min 1)               |
| `supportChannel` | `string`                                  | No       | Slack support channel                            |
| `draft`          | `boolean`                                 | No       | Whether to start the associated track as a draft |
| `milestones`     | `array`                                   | No       | Milestones with pass rate targets                |
| `filter`         | `Filter` (~~`CatalogFilter`~~ deprecated) | No       | Entity inclusion filter                          |
| `exclude`        | `Filter`                                  | No       | Entity exclusion filter (requires `filter`)      |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{ "campaignId": "string", "trackId": "string" }
```

***

### `update-campaign`

Updates an existing campaign. Only provided fields are changed.

**Attributes:** `readOnly: false` · `idempotent: true`

**Parameters**

| Name             | Type                                              | Required | Description                                   |
| ---------------- | ------------------------------------------------- | -------- | --------------------------------------------- |
| `campaignId`     | `string`                                          | Yes      | ID of the campaign to update                  |
| `name`           | `string`                                          | No       | Campaign display name                         |
| `description`    | `string`                                          | No       | Campaign description                          |
| `ownerEntityRef` | `string`                                          | No       | Backstage entity ref of the owner             |
| `supportChannel` | `string`                                          | No       | Slack support channel                         |
| `startDate`      | `string`                                          | No       | Campaign start date (ISO 8601)                |
| `endDate`        | `string`                                          | No       | Campaign end date (ISO 8601)                  |
| `draft`          | `boolean`                                         | No       | Draft state of the associated track           |
| `checkIds`       | `string[]`                                        | No       | Replaces check IDs (min 1 if provided)        |
| `milestones`     | `array`                                           | No       | Replaces existing milestones                  |
| `includeFilter`  | `Filter \| null` (~~`CatalogFilter`~~ deprecated) | No       | Entity inclusion filter; pass `null` to clear |
| `excludeFilter`  | `Filter \| null`                                  | No       | Entity exclusion filter; pass `null` to clear |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{ "campaignId": "string", "trackId": "string" }
```

***

### `delete-campaign`

Permanently deletes a campaign.

**Attributes:** `readOnly: false` · `idempotent: false`

**Parameters**

| Name         | Type     | Required | Description                  |
| ------------ | -------- | -------- | ---------------------------- |
| `campaignId` | `string` | Yes      | ID of the campaign to delete |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{ "campaignId": "string", "deleted": true }
```

***

### `list-campaigns`

Returns all Soundcheck campaigns with their IDs, names, status, associated track IDs, and date ranges.

**Attributes:** `readOnly: true` · `idempotent: true`

**Parameters:** None

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "campaigns": [
    {
      "id": "string",
      "name": "string",
      "archived": false,
      "trackId": "string",
      "startDate": "string",
      "targetCompletionDate": "string"
    }
  ]
}
```

***

### `get-campaign-details`

Returns the full configuration of a campaign: name, description, owner, status, dates, milestones, check IDs, and entity filter.

**Attributes:** `readOnly: true` · `idempotent: true`

**Parameters**

| Name         | Type     | Required | Description        |
| ------------ | -------- | -------- | ------------------ |
| `campaignId` | `string` | Yes      | ID of the campaign |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "id": "string",
  "name": "string",
  "description": "string",
  "owner": "string",
  "supportChannel": "string",
  "archived": false,
  "trackId": "string",
  "startDate": "string",
  "targetCompletionDate": "string",
  "filter": {},
  "checkIds": ["string"],
  "milestones": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "targetPercent": 0,
      "targetCompletionDate": "string"
    }
  ]
}
```

***

## Exemptions

### `set-exemption`

Exempts a component from a specific check with a documented justification. The exemption takes effect immediately.

**Attributes:** `readOnly: false` · `idempotent: true`

**Parameters**

| Name            | Type     | Required | Description                                            |
| --------------- | -------- | -------- | ------------------------------------------------------ |
| `entityRef`     | `string` | Yes      | Entity reference (e.g. `component:default/my-service`) |
| `checkId`       | `string` | Yes      | ID of the check to exempt                              |
| `justification` | `string` | Yes      | Reason for the exemption                               |
| `userRef`       | `string` | Yes      | User reference (e.g. `user:default/jsmith`)            |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "checkId": "string",
  "entityRef": "string",
  "justification": "string",
  "timestamp": "string"
}
```

***

### `remove-exemption`

Removes an active exemption for a component from a specific check. If no exemption exists, the action is a no-op.

**Attributes:** `readOnly: false` · `idempotent: true`

**Parameters**

| Name        | Type     | Required | Description      |
| ----------- | -------- | -------- | ---------------- |
| `entityRef` | `string` | Yes      | Entity reference |
| `checkId`   | `string` | Yes      | ID of the check  |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{ "checkId": "string", "entityRef": "string", "removed": true }
```

***

### `list-exemptions`

Returns all active exemptions for a component, including the check name and justification for each.

**Attributes:** `readOnly: true` · `idempotent: true`

**Parameters**

| Name        | Type     | Required | Description      |
| ----------- | -------- | -------- | ---------------- |
| `entityRef` | `string` | Yes      | Entity reference |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "exemptions": [
    {
      "checkId": "string",
      "reason": "string",
      "userRef": "string",
      "timestamp": "string"
    }
  ]
}
```

***

## Entity compliance

### `get-component-health`

Returns overall compliance score, level, track memberships, and pass/fail check counts for a component.

**Attributes:** `readOnly: true` · `idempotent: true`

**Parameters**

| Name        | Type     | Required | Description                                            |
| ----------- | -------- | -------- | ------------------------------------------------------ |
| `entityRef` | `string` | Yes      | Entity reference (e.g. `component:default/my-service`) |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "entityRef": "string",
  "overallScore": 0.0,
  "passingChecks": 0,
  "failingChecks": 0,
  "tracks": [
    {
      "trackId": "string",
      "trackName": "string",
      "highestCertifiedLevel": "string",
      "levels": [
        {
          "name": "string",
          "passingChecks": 0,
          "failingChecks": 0,
          "score": 0.0
        }
      ]
    }
  ]
}
```

***

### `list-failing-checks`

Returns all failing checks for a component, optionally filtered by track.

**Attributes:** `readOnly: true` · `idempotent: true`

**Parameters**

| Name        | Type     | Required | Description                        |
| ----------- | -------- | -------- | ---------------------------------- |
| `entityRef` | `string` | Yes      | Entity reference                   |
| `trackId`   | `string` | No       | Filter results to a specific track |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "checks": [
    {
      "checkId": "string",
      "checkName": "string",
      "trackId": "string",
      "trackName": "string",
      "lastRunAt": "string",
      "failureReason": "string"
    }
  ]
}
```

***

## Facts

### `list-entity-facts`

Returns metadata about facts collected for a given entity. Use `get-fact-data` to retrieve the actual value of a specific fact.

**Attributes:** `readOnly: true` · `idempotent: true`

**Parameters**

| Name        | Type       | Required | Description                                            |
| ----------- | ---------- | -------- | ------------------------------------------------------ |
| `entityRef` | `string`   | Yes      | Entity reference (e.g. `component:default/my-service`) |
| `factRefs`  | `string[]` | No       | Filter to specific fact references                     |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "facts": [
    {
      "factRef": "string",
      "collectorId": "string",
      "factId": "string",
      "timestamp": "string",
      "error": "string"
    }
  ],
  "message": "string"
}
```

***

### `get-fact-data`

Returns the raw fact value for a specific fact from a specific collector for a given entity.

**Attributes:** `readOnly: true` · `idempotent: true`

**Parameters**

| Name          | Type     | Required | Description                                         |
| ------------- | -------- | -------- | --------------------------------------------------- |
| `entityRef`   | `string` | Yes      | Entity reference                                    |
| `collectorId` | `string` | Yes      | ID of the fact collector (e.g. `catalog`, `github`) |
| `factId`      | `string` | Yes      | Name of the fact within the collector               |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "factRef": "string",
  "collectorId": "string",
  "factId": "string",
  "value": null,
  "timestamp": "string"
}
```

***

## Org intelligence

### `get-org-compliance-summary`

Returns a high-level overview of tech health posture across all tracks: overall score, component counts, trends, and track summaries.

**Attributes:** `readOnly: true` · `idempotent: true`

**Parameters**

| Name               | Type       | Required | Description                                         |
| ------------------ | ---------- | -------- | --------------------------------------------------- |
| `scope`            | `string`   | No       | Filter by scope (e.g. `"default"`)                  |
| `tracks`           | `array`    | No       | Limit results to specific tracks                    |
| `entityKinds`      | `string[]` | No       | Filter by entity kinds (e.g. `["Component"]`)       |
| `entityLifecycles` | `string[]` | No       | Filter by entity lifecycles (e.g. `["production"]`) |
| `numberOfDays`     | `number`   | No       | Number of days for trend data (default: `30`)       |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "overallPassRate": 0.0,
  "totalTracksActive": 0,
  "totalGroups": 0,
  "levelBreakdown": [
    {
      "levelOrdinal": 0,
      "levelName": "string",
      "snapshotPassRate": 0.0,
      "trend": "improving | declining | stable"
    }
  ],
  "trackSummaries": [
    {
      "trackId": "string",
      "trackName": "string",
      "overallSnapshotPassRate": 0.0
    }
  ]
}
```

***

### `get-team-compliance-summary`

Returns aggregated compliance scores and track breakdown for a specific team.

**Attributes:** `readOnly: true` · `idempotent: true`

**Parameters**

| Name             | Type     | Required | Description                                                 |
| ---------------- | -------- | -------- | ----------------------------------------------------------- |
| `groupEntityRef` | `string` | Yes      | Group entity ref of the team (e.g. `group:default/my-team`) |
| `tracks`         | `array`  | No       | Limit results to specific tracks                            |
| `numberOfDays`   | `number` | No       | Number of days for trend data                               |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "groupEntityRef": "string",
  "groupTitle": "string",
  "snapshotPassRate": 0.0,
  "trend": "improving | declining | stable",
  "trackBreakdown": [
    {
      "trackId": "string",
      "trackName": "string",
      "levels": [
        { "levelOrdinal": 0, "levelName": "string", "snapshotPassRate": 0.0 }
      ]
    }
  ]
}
```

***

### `get-top-failing-checks`

Returns the checks with the highest failure rates across the org, with optional filtering.

**Attributes:** `readOnly: true` · `idempotent: true`

**Parameters**

| Name               | Type       | Required | Description                                |
| ------------------ | ---------- | -------- | ------------------------------------------ |
| `limit`            | `number`   | No       | Maximum number of results (default: `10`)  |
| `tracks`           | `array`    | No       | Limit results to checks in specific tracks |
| `scope`            | `string`   | No       | Filter by scope                            |
| `entityKinds`      | `string[]` | No       | Filter by entity kinds                     |
| `entityLifecycles` | `string[]` | No       | Filter by entity lifecycles                |
| `checkOwners`      | `string[]` | No       | Filter by check owner entity refs          |
| `numberOfDays`     | `number`   | No       | Number of days for trend data              |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "checks": [
    {
      "checkId": "string",
      "checkName": "string",
      "snapshotPassRate": 0.0,
      "failureRate": 0.0,
      "trend": "improving | declining | stable"
    }
  ]
}
```

***

### `get-compliance-trends`

Returns time-series compliance trend data for a track, showing per-level pass rates over the requested number of days.

**Attributes:** `readOnly: true` · `idempotent: true`

**Parameters**

| Name           | Type     | Required | Description                                  |
| -------------- | -------- | -------- | -------------------------------------------- |
| `trackId`      | `string` | Yes      | ID of the track                              |
| `numberOfDays` | `number` | No       | Number of days of trend data (default: `30`) |
| `scope`        | `string` | No       | Filter by scope                              |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "trackId": "string",
  "trackName": "string",
  "overallTrend": "improving | declining | stable",
  "levelTrends": [
    {
      "levelOrdinal": 0,
      "levelName": "string",
      "snapshotPassRate": 0.0,
      "trend": "improving | declining | stable",
      "trendPassRates": [0.0]
    }
  ]
}
```

***

### `compare-teams`

Returns a side-by-side compliance comparison for two or more teams, ranked by pass rate.

**Attributes:** `readOnly: true` · `idempotent: true`

**Parameters**

| Name              | Type       | Required | Description                                  |
| ----------------- | ---------- | -------- | -------------------------------------------- |
| `groupEntityRefs` | `string[]` | Yes      | Group entity refs to compare (min 2, max 10) |
| `tracks`          | `array`    | No       | Limit comparison to specific tracks          |
| `numberOfDays`    | `number`   | No       | Number of days for trend data                |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "comparison": [
    {
      "groupEntityRef": "string",
      "groupTitle": "string",
      "snapshotPassRate": 0.0,
      "trend": "improving | declining | stable",
      "rank": 1
    }
  ],
  "bestPerforming": "string",
  "worstPerforming": "string",
  "spread": 0.0
}
```

***

### `get-rolled-up-tech-insights`

Returns a track-scoped compliance overview with top and bottom performing groups, mirroring the Tech Insights Explorer page.

**Attributes:** `readOnly: true` · `idempotent: true`

**Parameters**

| Name               | Type       | Required | Description                                          |
| ------------------ | ---------- | -------- | ---------------------------------------------------- |
| `trackId`          | `string`   | Yes      | ID of the track to explore                           |
| `limit`            | `number`   | No       | Number of top/bottom groups to return (default: `5`) |
| `numberOfDays`     | `number`   | No       | Number of days for trend data                        |
| `entityKinds`      | `string[]` | No       | Filter by entity kinds                               |
| `entityLifecycles` | `string[]` | No       | Filter by entity lifecycles                          |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "trackId": "string",
  "trackName": "string",
  "overallSnapshotPassRate": 0.0,
  "levelBreakdown": [
    { "levelOrdinal": 0, "levelName": "string", "snapshotPassRate": 0.0 }
  ],
  "topPerformingGroups": [
    {
      "groupEntityRef": "string",
      "groupTitle": "string",
      "snapshotPassRate": 0.0
    }
  ],
  "bottomPerformingGroups": [
    {
      "groupEntityRef": "string",
      "groupTitle": "string",
      "snapshotPassRate": 0.0
    }
  ],
  "totalGroupCount": 0
}
```

***

### `find-struggling-components`

Returns the components with the lowest compliance pass rates, sorted by severity. Useful for champions identifying which teams need support.

**Attributes:** `readOnly: true` · `idempotent: true`

**Parameters**

| Name                   | Type       | Required | Description                                                        |
| ---------------------- | ---------- | -------- | ------------------------------------------------------------------ |
| `limit`                | `number`   | No       | Maximum number of components (default: `20`)                       |
| `failureRateThreshold` | `number`   | No       | Only return components at or below this pass rate (default: `0.5`) |
| `tracks`               | `array`    | No       | Limit results to components applicable to specific tracks          |
| `entityKinds`          | `string[]` | No       | Filter by entity kinds                                             |
| `entityTypes`          | `string[]` | No       | Filter by entity types                                             |
| `entityLifecycles`     | `string[]` | No       | Filter by entity lifecycles                                        |
| `entityOwners`         | `string[]` | No       | Filter by owner group entity refs                                  |
| `numberOfDays`         | `number`   | No       | Number of days for trend data                                      |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "components": [
    {
      "entityRef": "string",
      "entityTitle": "string",
      "ownerRef": "string",
      "snapshotPassRate": 0.0,
      "trend": "improving | declining | stable"
    }
  ],
  "totalBelowThreshold": 0
}
```

***

### `get-compliance-by-level`

Returns adoption metrics for a specific level within a track: component counts, percentages, and top failing components.

**Attributes:** `readOnly: true` · `idempotent: true`

**Parameters**

| Name      | Type     | Required | Description                                          |
| --------- | -------- | -------- | ---------------------------------------------------- |
| `trackId` | `string` | Yes      | ID of the track                                      |
| `level`   | `string` | Yes      | Name of the level within the track (e.g. `"Bronze"`) |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "trackId": "string",
  "level": "string",
  "count": 0,
  "totalComponents": 0,
  "percentage": 0,
  "failingComponents": ["string"]
}
```

***

## Integrations

### `get-integration-status`

Diagnoses the configuration of a Soundcheck fact collector integration: returns status, available facts, collection schedule, and any configuration errors.

**Attributes:** `readOnly: true` · `idempotent: true`

**Parameters**

| Name            | Type     | Required | Description                                    |
| --------------- | -------- | -------- | ---------------------------------------------- |
| `integrationId` | `string` | Yes      | ID or name of the integration (fact collector) |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "integrationId": "string",
  "name": "string",
  "status": "healthy | misconfigured",
  "factNames": ["string"],
  "scheduledCollections": 0,
  "latestCompletedTime": "string",
  "latestFailedTime": "string",
  "errors": ["string"]
}
```

***

### `get-integration-config-schema`

Returns the JSON Schema describing the configuration format for a Soundcheck integration. Use this before `configure-integration` to understand the required fields.

**Attributes:** `readOnly: true` · `idempotent: true`

**Parameters**

| Name            | Type     | Required | Description                                    |
| --------------- | -------- | -------- | ---------------------------------------------- |
| `integrationId` | `string` | Yes      | ID or name of the integration (fact collector) |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{
  "integrationId": "string",
  "name": "string",
  "isConfigurable": true,
  "isEditable": true,
  "configSchema": null,
  "currentConfig": null
}
```

***

### `configure-integration`

Configures a Soundcheck fact collector integration with the provided settings. Use `get-integration-config-schema` first to understand the required configuration format.

**Attributes:** `readOnly: false` · `idempotent: true`

**Parameters**

| Name            | Type                      | Required | Description                                                           |
| --------------- | ------------------------- | -------- | --------------------------------------------------------------------- |
| `integrationId` | `string`                  | Yes      | ID or name of the integration                                         |
| `config`        | `Record<string, unknown>` | Yes      | Configuration object for the integration                              |
| `shouldSync`    | `boolean`                 | No       | Whether to trigger a sync after updating the config (default: `true`) |

**Returns:**

```json theme={"theme":{"light":"github-light","dark":"dracula"}}
{ "integrationId": "string", "name": "string", "success": true }
```