# Group Tools

Use the group tools to browse the readable organization tree of the workspace bound to your API key.

## Available tools

| Tool                        | Purpose                                               |
| --------------------------- | ----------------------------------------------------- |
| `group_list`                | List readable groups in the current workspace.        |
| `group_find`                | Search groups by query.                               |
| `group_get_summary`         | Return the main organizational summary for one group. |
| `group_get_support_context` | Return support-oriented context for one group.        |

## `group_list`

List readable groups in the current workspace.

This tool does not take any parameters.

### Response

```json
{
  "items": [
    {
      "publicId": "grp_01hj5kq4k4a2v3x7p9m8n6c2dz",
      "name": "Sales",
      "isDefault": false
    }
  ]
}
```

### Notes

* The response is capped to the first 25 readable groups.
* `isDefault` identifies the default group configured in the workspace.

## `group_find`

Search groups by name.

### Parameters

| Name    | Type    | Required | Description                                 |
| ------- | ------- | -------- | ------------------------------------------- |
| `query` | String  | Yes      | Search query. Maximum length: `190`.        |
| `limit` | Integer | No       | Result limit. Default: `10`. Maximum: `10`. |

### Response

```json
{
  "items": [
    {
      "publicId": "grp_01hj5kq4k4a2v3x7p9m8n6c2dz",
      "name": "Sales",
      "isDefault": false
    }
  ]
}
```

## `group_get_summary`

Return the main organizational summary for a single group.

### Parameters

| Name            | Type   | Required | Description                                       |
| --------------- | ------ | -------- | ------------------------------------------------- |
| `groupPublicId` | String | Yes      | Group public ID in `grp_<lowercase_ulid>` format. |

### Response

```json
{
  "publicId": "grp_01hj5kq4k4a2v3x7p9m8n6c2dz",
  "name": "Sales",
  "workspace": {
    "name": "Acme"
  },
  "hierarchy": {
    "parent": {
      "publicId": "grp_01hj5jq4k4a2v3x7p9m8n6c2da",
      "name": "Europe"
    },
    "childrenCount": 3,
    "depth": 2
  },
  "configuration": {
    "fixedFieldsCount": 4,
    "hasLogo": true,
    "hasPrimaryColor": true,
    "hasSecondaryColor": true,
    "hasVcardLogo": false,
    "hasVcardHeader": true,
    "hasVcardFooter": false,
    "hasVcardBackgroundImage": false
  },
  "metrics": {
    "users": 42
  },
  "flags": {
    "isDefault": false,
    "hasParent": true,
    "hasChildren": true
  }
}
```

### Field notes

* `hierarchy.depth` is based on the number of ancestors in the group tree.
* `metrics.users` is only returned when the caller can read user data for that workspace.
* `configuration` exposes compact booleans and counts, not the underlying design payloads.

## `group_get_support_context`

Return support-oriented context for a single group.

### Parameters

| Name            | Type   | Required | Description                                       |
| --------------- | ------ | -------- | ------------------------------------------------- |
| `groupPublicId` | String | Yes      | Group public ID in `grp_<lowercase_ulid>` format. |

### Response

```json
{
  "group": {
    "publicId": "grp_01hj5kq4k4a2v3x7p9m8n6c2dz",
    "name": "Sales",
    "isDefault": false
  },
  "workspace": {
    "name": "Acme"
  },
  "hierarchy": {
    "parent": {
      "publicId": "grp_01hj5jq4k4a2v3x7p9m8n6c2da",
      "name": "Europe"
    },
    "childrenCount": 3,
    "children": [
      {
        "publicId": "grp_01hj5mq4k4a2v3x7p9m8n6c2db",
        "name": "Field Sales"
      }
    ],
    "depth": 2
  },
  "configuration": {
    "fixedFieldsCount": 4,
    "hasLogo": true,
    "hasPrimaryColor": true,
    "hasSecondaryColor": true,
    "hasVcardLogo": false,
    "hasVcardHeader": true,
    "hasVcardFooter": false,
    "hasVcardBackgroundImage": false
  },
  "metrics": {
    "users": 42
  },
  "flags": {
    "isDefault": false,
    "hasParent": true,
    "hasChildren": true
  }
}
```

### Field notes

* `hierarchy.children` is capped to the first 10 readable direct children.
* This tool is intended for support and operational triage, not full organization export.