> For the complete documentation index, see [llms.txt](https://docs.autommate.com/userguide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.autommate.com/userguide/mcp-and-ai-reference/tools/users-search.md).

# users\_search — Find tenant user accounts

**Declared contract — reviewed 21 October 2026.** This page describes the tool exposed by the Autom Mate New connection in the inspected 71-tool profile. It does not establish support on every build or prove runtime success. Check the active connection and [installed product version](https://docs.autommate.com/userguide/start-here/documentation-scope-and-product-versions.md). Historical examples retain their original observation dates. Logical tool names may have a client-specific namespace prefix.

Find tenant user-account metadata: display name, email, roles and status. The query searches names and email addresses. This is not a contact directory or activity-history tool.

## Declared request signature

The following is the exposed 21 October declaration; request types do not define an exhaustive response schema.

```ts
declare const tools: { mcp__codex_apps__autom_mate_new_users_search(args: { cursor?: string; page_size?: number; query?: string; role?: string; sort_by?: "user_name" | "first_name" | "user_email" | "updated_at"; status?: "active" | "disabled"; }): Promise<CallToolResult>; };
```

## Parameters

| Parameter   | Type                                                     | Required | Meaning                                                           |
| ----------- | -------------------------------------------------------- | -------- | ----------------------------------------------------------------- |
| `query`     | string                                                   | No       | Name or email search.                                             |
| `role`      | string                                                   | No       | Role filter. The exposed schema does not list allowed role names. |
| `status`    | `active` or `disabled`                                   | No       | Account status filter.                                            |
| `sort_by`   | `user_name`, `first_name`, `user_email`, or `updated_at` | No       | Sort field.                                                       |
| `page_size` | number                                                   | No       | Requested page size.                                              |
| `cursor`    | string                                                   | No       | Returned pagination cursor.                                       |

## Minimal request

Replace the placeholder with the specific account search requested by the user. Use only role values known for the connected environment; this contract does not enumerate them.

```json
{
  "query": "<name or email to look up>"
}
```

## Read the result

* Technician accounts are excluded by this tool's contract. A missing row is not proof that the person has no account.
* An access refusal means the caller cannot read the directory; it must not be reported as zero users.
* Use account metadata only for the requested task. This response does not provide login history, activity or contact-consent information.
* For another page, keep the same filters and pass the returned cursor unchanged. Treat the cursor as opaque; stop when no continuation is returned. The first page need not be the complete result set.

## Permissions and retries

Read-only tenant-account lookup. Respect the connected user's access and disclose only the account details needed for the task. Resolve a refusal through the supported access process; do not treat alternate searches as a way around it.

## Present a requested result

When the user asked to see this result, pass the returned `result_ref` to `show_result` once for the final requested answer. Do not show cards for intermediate lookups. A result reference expires after 15 minutes; read again if it has expired. This presentation step neither executes nor verifies a business action.

## Continue

* Next tools: [`platform_get_summary`](https://docs.autommate.com/userguide/mcp-and-ai-reference/tools/platform-get-summary).
* Workflow: [Discovery tool contracts](https://docs.autommate.com/userguide/mcp-and-ai-reference/discovery-tool-contracts.md).
* Worked reference: [Read discovery results and pagination](https://docs.autommate.com/userguide/mcp-and-ai-reference/read-discovery-results-and-pagination.md).
* [MCP tool reference](https://docs.autommate.com/userguide/mcp-and-ai-reference/tools).
