MCP Reference

account_list_users

List Users

Beschreibung

Lists the people on the account — resolve @handle mentions, pick a user_id target, or show a roster.

Admin and employer callers additionally see email, phone_number, time_zone (contact-sensitive data) and employment-time metadata: working_hours — the merged shape from ENG-1434 with start_at (HH:MM), paused_minutes, and hours_by_weekday ({"mon": 8.0, …}, missing key = not a workday); plus checkin_not_required (exempt from clock-in/out logic, e.g. C-level), and standup_not_required. include_inactive defaults to true so historical mentions still resolve; pass false for a live roster. search is a case-insensitive substring over handle / first_name / last_name (+ email for admin/employer).

Zugriff

Zugriffsprofil: basic. Module: none. Die Freigabe im Profil ersetzt keine Account-, Workspace- oder Rollenberechtigung.

Parameter

Name	Typ	Pflicht	Beschreibung
`account_id`	string	Ja	Account prefix ID (e.g., acct_abc123). Discover via account_list.
`include_inactive`	boolean	Nein	Include inactive (departed) users so historical @handles still resolve. Default true. Pass false for a live-roster view.
`search`	string	Nein	Case-insensitive substring, 1+ chars. Matches handle / first_name / last_name (admin/employer: also email). Use for narrowing before pulling the full list.

Eingabeschema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "account_id": {
      "type": "string",
      "description": "Account prefix ID (e.g., acct_abc123). Discover via account_list."
    },
    "include_inactive": {
      "type": "boolean",
      "description": "Include inactive (departed) users so historical @handles still resolve. Default true. Pass false for a live-roster view."
    },
    "search": {
      "type": "string",
      "description": "Case-insensitive substring, 1+ chars. Matches handle / first_name / last_name (admin/employer: also email). Use for narrowing before pulling the full list."
    }
  },
  "required": [
    "account_id"
  ],
  "type": "object"
}

Ausgabeschema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "users": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "User prefix ID (user_…) — pass to tools that accept user_id (handle also accepted)."
          },
          "db_id": {
            "type": "integer",
            "description": "Integer PK — matches user.db_id in chat/time-clock/standup response rows."
          },
          "handle": {
            "type": "string",
            "description": "Unique within the account; what @handle mentions reference."
          },
          "name": {
            "type": "string"
          },
          "position": {
            "type": [
              "string",
              "null"
            ],
            "description": "Omitted for external (guest) callers."
          },
          "remote_worker": {
            "type": "boolean",
            "description": "Omitted for external (guest) callers."
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "inactive"
            ],
            "description": "Omitted for external (guest) callers."
          },
          "roles": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "admin",
                "employer"
              ]
            },
            "description": "Empty = regular member."
          },
          "is_agent": {
            "type": "boolean",
            "description": "True if this user is a bot account (AI participant). Treat the row as an agent rather than a person — don't ask the bot for human feedback; don't assign tasks expecting human work."
          },
          "email": {
            "type": "string",
            "description": "Only present for admin/employer callers."
          },
          "phone_number": {
            "type": [
              "string",
              "null"
            ],
            "description": "Only present for admin/employer callers."
          },
          "time_zone": {
            "type": [
              "string",
              "null"
            ],
            "description": "Rails TimeZone display label (e.g. 'Berlin'), not an IANA id. Only for admin/employer callers."
          },
          "working_hours": {
            "type": "object",
            "description": "ENG-1434. Merged working-hours record for this member. `start_at` HH:MM daily start, `paused_minutes` daily break, `hours_by_weekday` a map of weekday → Float hours (missing key = not a workday for this member; don't flag them missing). Only present for admin/employer callers.",
            "properties": {
              "start_at": {
                "type": "string"
              },
              "paused_minutes": {
                "type": "integer"
              },
              "hours_by_weekday": {
                "type": "object",
                "description": "e.g. {\"mon\": 8.0, \"fri\": 4.0}"
              }
            }
          },
          "checkin_not_required": {
            "type": "boolean",
            "description": "True when the user is exempt from clock-in/out (C-level, etc.) — attendance logic must NOT flag them as missing. Only present for admin/employer callers."
          },
          "standup_not_required": {
            "type": "boolean",
            "description": "True when the user is exempt from the daily standup roster. Only present for admin/employer callers."
          }
        },
        "required": [
          "id",
          "db_id",
          "handle",
          "name",
          "roles",
          "is_agent"
        ]
      }
    }
  },
  "required": [
    "users"
  ],
  "type": "object"
}