# User Tools

Use the user tools to search users and retrieve support-oriented user context from the workspace bound to your API key.

## Available tools

| Tool                       | Purpose                                              |
| -------------------------- | ---------------------------------------------------- |
| `user_list`                | List readable users in the current workspace.        |
| `user_count`               | Count readable users with optional filters.          |
| `user_find`                | Search users with optional status and group filters. |
| `user_get_summary`         | Return the main operational summary for one user.    |
| `user_get_support_context` | Return support-specific context for one user.        |

## `user_list`

List readable users in the current workspace.

This tool does not take any parameters.

### Response

```json
{
  "items": [
    {
      "publicId": "usr_01hj5kq4k4a2v3x7p9m8n6c2dz",
      "email": "john.doe@example.com",
      "displayName": "John Doe",
      "status": "active",
      "group": "Sales"
    }
  ]
}
```

### Notes

* The response is capped to the first 25 readable users.
* Only users with a concrete status are returned: `active`, `inactive`, `hidden`, or `not_present`.
* Returned items use the same compact user reference shape as `user_find`.

## `user_count`

Count available users in the current workspace.

### Parameters

| Name     | Type   | Required | Description                                                                                      |
| -------- | ------ | -------- | ------------------------------------------------------------------------------------------------ |
| `query`  | String | No       | Optional search query. Maximum length: `190`.                                                    |
| `status` | String | No       | One of `active`, `inactive`, `hidden`, `not_present`.                                            |
| `field`  | String | No       | One of `any`, `email`, `total`. Default: `any`. `total` is accepted as a legacy alias for `any`. |

### Response

```json
{
  "count": 128,
  "query": "john",
  "field": "email",
  "status": "active"
}
```

### Notes

* When `query` is omitted or empty, `query` is returned as `null`.
* `count` only covers readable, non-deleted users with a non-null status in the workspace resolved from the API key.

## `user_find`

Search users by free text. Results are limited to available users in the current workspace.

### Parameters

| Name            | Type    | Required | Description                                           |
| --------------- | ------- | -------- | ----------------------------------------------------- |
| `query`         | String  | Yes      | Search query. Maximum length: `190`.                  |
| `status`        | String  | No       | One of `active`, `inactive`, `hidden`, `not_present`. |
| `groupPublicId` | String  | No       | Group public ID in `grp_<lowercase_ulid>` format.     |
| `limit`         | Integer | No       | Result limit. Default: `10`. Maximum: `10`.           |

### Response

```json
{
  "items": [
    {
      "publicId": "usr_01hj5kq4k4a2v3x7p9m8n6c2dz",
      "email": "john.doe@example.com",
      "displayName": "John Doe",
      "status": "active",
      "group": "Sales"
    }
  ]
}
```

### Notes

* Results only include readable, non-deleted users with a non-null status.
* `groupPublicId` must belong to a readable group in the current workspace.

## `user_get_summary`

Return the main operational summary for a single user.

### Parameters

| Name           | Type   | Required | Description                                      |
| -------------- | ------ | -------- | ------------------------------------------------ |
| `userPublicId` | String | Yes      | User public ID in `usr_<lowercase_ulid>` format. |

### Response

```json
{
  "publicId": "usr_01hj5kq4k4a2v3x7p9m8n6c2dz",
  "email": "john.doe@example.com",
  "displayName": "John Doe",
  "status": "active",
  "group": {
    "name": "Sales"
  },
  "workspace": {
    "name": "Acme"
  },
  "profile": {
    "identity": {
      "firstName": "John",
      "lastName": "Doe",
      "title": "Account Executive",
      "unit": "Revenue"
    },
    "contact": {
      "phone": "+33123456789",
      "mobile": "+33612345678",
      "secondEmail": "john.alt@example.com"
    },
    "address": {
      "streetAddr": "10 rue de Paris",
      "postalCode": "75001",
      "city": "Paris"
    },
    "formula": "Regards",
    "supplementaryLinks": {
      "calendar": "https://cal.example.com/john",
      "linkedin": "john-doe"
    },
    "extraFields": {
      "extra1": "Custom value"
    }
  },
  "connectors": {
    "tenant": "Microsoft 365",
    "sourceConnector": "azure",
    "enabledConnectors": [
      "desktop_app",
      "chrome_extension"
    ]
  }
}
```

### Field notes

* `workspace` always describes the workspace resolved from the API key.
* `group` currently returns only the group name.
* `profile` is compacted server-side: empty sub-objects and empty values are omitted.
* `formula` is sanitized before being returned.
* `enabledConnectors` is a derived list and can contain values such as `salesforce`, `pipedrive`, `smartlead`, `outreach`, `datananas`, `desktop_app`, and `chrome_extension`.
* `supplementaryLinks` and `extraFields` can appear in the profile payload, but they are excluded from workspace completeness metrics.

## `user_get_support_context`

Return support-focused information about licensing, activation, and connector state for one user.

### Parameters

| Name           | Type   | Required | Description                                      |
| -------------- | ------ | -------- | ------------------------------------------------ |
| `userPublicId` | String | Yes      | User public ID in `usr_<lowercase_ulid>` format. |

### Response

```json
{
  "user": {
    "publicId": "usr_01hj5kq4k4a2v3x7p9m8n6c2dz",
    "email": "john.doe@example.com",
    "displayName": "John Doe",
    "status": "active",
    "group": "Sales"
  },
  "status": "active",
  "group": {
    "name": "Sales"
  },
  "license": {
    "hasLicense": true,
    "expiresAt": "2026-12-31T23:59:59+00:00"
  },
  "activation": {
    "desktopAppActivated": true,
    "vcardEnabled": true,
    "isAlias": false,
    "hasPhoto": true
  },
  "connectors": {
    "tenant": "Microsoft 365",
    "sourceConnector": "azure",
    "enabledConnectors": [
      "desktop_app",
      "chrome_extension"
    ]
  },
  "flags": {
    "hasGroup": true,
    "hasTenant": true,
    "hasSecondEmail": false,
    "hasLicense": true
  }
}
```

### Field notes

* `user` merges the lightweight user reference with the compacted profile payload.
* `license.hasLicense` is the primary support flag for licensing.
* `license.expiresAt` is `null` when there is no expiration date.
* `activation.isAlias` is `true` for alias users.
* `activation.desktopAppActivated` is a boolean, not a timestamp.
* `flags` provides fast booleans for support workflows without extra client-side inference.