Skip to main content
Glama

List users

list_users
Read-onlyIdempotent

List, search, or count an instance's users (like clerk users list). Use user_id or an exact email_address to look up a single user. Returns data, a page of Backend API user objects without private_metadata, and total_count, the total matching users across all pages. To get a count with minimal data, set limit to 1 and read total_count. Filters match the Backend API list-users query; date filters use Unix epoch milliseconds.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "application_id": "<application_id>",
      "instance": "<instance>"
    },
    "name": "list_users"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum users to return (default 100).
queryNoText to search for in email addresses, phone numbers, usernames, web3 wallets, user IDs, first names, and last names.
bannedNoReturn banned users when true, or users who are not banned when false.
offsetNoNumber of users to skip, to page past earlier results. Omit to start from the first user.
user_idNoReturn only users with these Clerk user IDs (user_…).
instanceYesInstance to target: "development", "production", or a full instance ID (ins_…).
order_byNoField to sort by, prefixed with - for descending or + for ascending, e.g. -last_sign_in_at. Sortable fields: created_at, updated_at, last_sign_in_at, last_active_at, email_address, first_name, last_name, username, phone_number, web3_wallet. Omit to sort by -created_at, newest first.
providerNoOAuth provider, such as oauth_google. Must be combined with provider_user_id.
usernameNoFilter by username.
name_queryNoCase-insensitive partial match on names.
external_idNoReturn only users whose external_id, the ID your own system stored on the user, is one of these values.
web3_walletNoFilter by exact web3 wallet addresses. Accepts up to 100 addresses.
phone_numberNoFilter by phone number.
deprovisionedNoReturn deprovisioned users when true, or users who are not deprovisioned when false.
email_addressNoFilter by email address.
application_idYesClerk application ID (app_…).
username_queryNoCase-insensitive partial match on usernames.
organization_idNoFilter by organization membership (org_…). Prefix an ID with - to exclude its members or + to include them. Accepts up to 100 IDs.
created_at_afterNoReturn users created after this Unix timestamp in milliseconds.
provider_user_idNoFilter by external account user IDs for the specified provider. Must be combined with provider. Accepts up to 100 IDs.
created_at_beforeNoReturn users created before this Unix timestamp in milliseconds.
phone_number_queryNoCase-insensitive partial match on phone numbers.
email_address_queryNoCase-insensitive partial match on email addresses.
last_active_at_afterNoReturn users whose last session activity was after this Unix timestamp in milliseconds.
last_active_at_sinceNoDeprecated inclusive activity filter in Unix epoch milliseconds. Prefer last_active_at_after, which takes precedence when both are set.
last_active_at_beforeNoReturn users whose last session activity was before this Unix timestamp in milliseconds.
last_sign_in_at_afterNoReturn users whose last sign-in was after this Unix timestamp in milliseconds.
last_sign_in_at_beforeNoReturn users whose last sign-in was before this Unix timestamp in milliseconds.

Output Schema

NameRequiredDescriptionDefault
dataYes
total_countYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed23 schema fields changed
    • addedInput schema / properties / banned
      Added value: +{
      +  "description": "Return banned users when true, or users who are not banned when false.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / created_at_after
      Added value: +{
      +  "description": "Return users created after this Unix timestamp in milliseconds.",
      +  "maximum": 9007199254740991,
      +  "minimum": -9007199254740991,
      +  "type": "integer"
      +}
    • addedInput schema / properties / created_at_before
      Added value: +{
      +  "description": "Return users created before this Unix timestamp in milliseconds.",
      +  "maximum": 9007199254740991,
      +  "minimum": -9007199254740991,
      +  "type": "integer"
      +}
    • addedInput schema / properties / deprovisioned
      Added value: +{
      +  "description": "Return deprovisioned users when true, or users who are not deprovisioned when false.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / email_address_query
      Added value: +{
      +  "description": "Case-insensitive partial match on email addresses.",
      +  "type": "string"
      +}
    • changedInput schema / properties / external_id / description
      Previous value: -"Filter by external ID."New value: +"Return only users whose external_id, the ID your own system stored on the user, is one of these values."
    • addedInput schema / properties / last_active_at_after
      Added value: +{
      +  "description": "Return users whose last session activity was after this Unix timestamp in milliseconds.",
      +  "maximum": 9007199254740991,
      +  "minimum": -9007199254740991,
      +  "type": "integer"
      +}
    • addedInput schema / properties / last_active_at_before
      Added value: +{
      +  "description": "Return users whose last session activity was before this Unix timestamp in milliseconds.",
      +  "maximum": 9007199254740991,
      +  "minimum": -9007199254740991,
      +  "type": "integer"
      +}
    • addedInput schema / properties / last_active_at_since
      Added value: +{
      +  "description": "Deprecated inclusive activity filter in Unix epoch milliseconds. Prefer last_active_at_after, which takes precedence when both are set.",
      +  "maximum": 9007199254740991,
      +  "minimum": -9007199254740991,
      +  "type": "integer"
      +}
    • addedInput schema / properties / last_sign_in_at_after
      Added value: +{
      +  "description": "Return users whose last sign-in was after this Unix timestamp in milliseconds.",
      +  "maximum": 9007199254740991,
      +  "minimum": -9007199254740991,
      +  "type": "integer"
      +}
    • addedInput schema / properties / last_sign_in_at_before
      Added value: +{
      +  "description": "Return users whose last sign-in was before this Unix timestamp in milliseconds.",
      +  "maximum": 9007199254740991,
      +  "minimum": -9007199254740991,
      +  "type": "integer"
      +}
    • addedInput schema / properties / name_query
      Added value: +{
      +  "description": "Case-insensitive partial match on names.",
      +  "type": "string"
      +}
    • changedInput schema / properties / offset / description
      Previous value: -"Users to skip before returning results."New value: +"Number of users to skip, to page past earlier results. Omit to start from the first user."
    • changedInput schema / properties / order_by / description
      Previous value: -"Sort field, e.g. -last_sign_in_at."New value: +"Field to sort by, prefixed with - for descending or + for ascending, e.g. -last_sign_in_at. Sortable fields: created_at, updated_at, last_sign_in_at, last_active_at, email_address, first_name, last_name, username, phone_number, web3_wallet. Omit to sort by -created_at, newest first."
    • addedInput schema / properties / organization_id
      Added value: +{
      +  "description": "Filter by organization membership (org_…). Prefix an ID with - to exclude its members or + to include them. Accepts up to 100 IDs.",
      +  "items": {
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedInput schema / properties / phone_number_query
      Added value: +{
      +  "description": "Case-insensitive partial match on phone numbers.",
      +  "type": "string"
      +}
    • addedInput schema / properties / provider
      Added value: +{
      +  "description": "OAuth provider, such as oauth_google. Must be combined with provider_user_id.",
      +  "type": "string"
      +}
    • addedInput schema / properties / provider_user_id
      Added value: +{
      +  "description": "Filter by external account user IDs for the specified provider. Must be combined with provider. Accepts up to 100 IDs.",
      +  "items": {
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • changedInput schema / properties / query / description
      Previous value: -"Search across common user fields."New value: +"Text to search for in email addresses, phone numbers, usernames, web3 wallets, user IDs, first names, and last names."
    • changedInput schema / properties / user_id / description
      Previous value: -"Filter by user ID."New value: +"Return only users with these Clerk user IDs (user_…)."
    • addedInput schema / properties / username_query
      Added value: +{
      +  "description": "Case-insensitive partial match on usernames.",
      +  "type": "string"
      +}
    • addedInput schema / properties / web3_wallet
      Added value: +{
      +  "description": "Filter by exact web3 wallet addresses. Accepts up to 100 addresses.",
      +  "items": {
      +    "minLength": 1,
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "https://json-schema.org/draft/2020-12/schema",
      +  "additionalProperties": {},
      +  "properties": {
      +    "data": {
      +      "items": {
      +        "additionalProperties": {},
      +        "description": "Backend API user object.",
      +        "properties": {
      +          "id": {
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "id"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "total_count": {
      +      "type": "number"
      +    }
      +  },
      +  "required": [
      +    "data",
      +    "total_count"
      +  ],
      +  "type": "object"
      +}
  2. Added

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real context beyond them: results are a page of Backend API user objects with private_metadata stripped, total_count spans all pages (not just the page), and date filters use epoch milliseconds. Pagination semantics per se (limit default 100) are left to the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, front-loaded with purpose, then the single-lookup rule, then return shape, then the count trick and filter conventions. Dense but every sentence carries information; the CLI analogy adds a small amount of framing overhead.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 28 parameters, a rich schema, and an output schema, the definition covers what the schema cannot: what the payload omits (private_metadata), that total_count is global, and how to cheaply obtain counts. Thin spots are minor – no mention of how offset interacts with total_count or of rate limits, both largely inferable from the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, and the description adds meaning on top: the limit=1/total_count counting idiom and the fact that total_count is cross-page are cross-parameter behavior the schema cannot express. It also confirms date filters are Unix epoch ms, reinforcing rather than duplicating the field docs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States specific verbs (list, search, count) and the resource (an instance's users), anchors it to the equivalent CLI command, and flags the single-user lookup path. An agent can tell this is the read/list entry point for users rather than one of the many organization or application list tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear condition for the single-user path (user_id or exact email_address) and a concrete recipe for count-only queries (limit=1 plus total_count). It stops short of naming when not to use it or pointing at siblings such as create_user/update_user, but the read/write split is evident from the annotations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources