# Workspace Tools

Use the workspace tools to retrieve read-only coverage and assignment metrics aggregated at workspace level.

These tools intentionally expose bounded operational summaries, not raw user exports.

## Available tools

| Tool                                         | Purpose                                                                                 |
| -------------------------------------------- | --------------------------------------------------------------------------------------- |
| `workspace_get_user_profile_completeness`    | Return profile completeness metrics for readable active users.                          |
| `workspace_get_campaign_assignment_overview` | Return campaign assignment counts, percentages, and averages for readable active users. |
| `workspace_get_group_completeness`           | Return profile completeness metrics grouped by readable group.                          |

## `workspace_get_user_profile_completeness`

Return the completeness coverage of tracked live profile fields for readable active users in the current workspace.

This tool does not take any parameters.

### Response

```json
{
  "workspace": {
    "name": "Acme"
  },
  "totals": {
    "activeReadableUsers": 128
  },
  "coverageModel": "tracked_live_fields",
  "trackedSections": [
    {
      "name": "identity",
      "fields": ["firstName", "lastName", "title", "unit"]
    },
    {
      "name": "contact",
      "fields": ["phone", "mobile", "secondEmail"]
    },
    {
      "name": "address",
      "fields": ["streetAddr", "postalCode", "city"]
    }
  ],
  "coverage": {
    "identity": {
      "fields": {
        "firstName": {
          "filledUsers": 126,
          "percentage": 98
        }
      }
    }
  }
}
```

### Field notes

* The `tracked_live_fields` model only covers `identity`, `contact`, and `address`.
* `formula`, `supplementaryLinks`, and `extraFields` are intentionally excluded from workspace completeness.
* Percentages are rounded server-side to integers.

## `workspace_get_campaign_assignment_overview`

Return campaign assignment overview metrics for readable active users in the current workspace.

This tool does not take any parameters.

### Response

```json
{
  "workspace": {
    "name": "Acme"
  },
  "totals": {
    "activeReadableUsers": 128,
    "totalAssignments": 356,
    "usersWithoutAssignments": 17
  },
  "averages": {
    "campaignsPerUser": 2.78
  },
  "distribution": {
    "usersWithAtLeastOneAssignment": 111,
    "usersWithAtLeastOneAssignmentPercentage": 87
  }
}
```

### Field notes

* `campaignsPerUser` is rounded to two decimals.
* `usersWithAtLeastOneAssignmentPercentage` is rounded to an integer percentage.

## `workspace_get_group_completeness`

Return completeness coverage grouped by readable group in the current workspace.

This tool does not take any parameters.

### Response

```json
{
  "workspace": {
    "name": "Acme"
  },
  "coverageModel": "tracked_live_fields",
  "trackedSections": [
    {
      "name": "identity",
      "fields": ["firstName", "lastName", "title", "unit"]
    }
  ],
  "groups": [
    {
      "publicId": "grp_01hj5kq4k4a2v3x7p9m8n6c2dz",
      "name": "Sales",
      "users": 42,
      "coverage": {
        "identity": {
          "fields": {
            "firstName": {
              "filledUsers": 42,
              "percentage": 100
            }
          }
        }
      }
    }
  ]
}
```

### Field notes

* `groups` is sorted by descending user count.
* Groups with zero readable users can still appear with zeroed coverage metrics.
* The coverage model and tracked sections are the same as `workspace_get_user_profile_completeness`.