> 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/automs-search.md).

# automs\_search — Find Hyperflows

**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 an existing Hyperflow by name and obtain the `autom_id` needed by inspection, execution and failure tools. Search matches names, not descriptions.

## 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_automs_search(args: { autom_group_id?: string; cursor?: string; page_size?: number; query?: string; type_id?: string; }): Promise<CallToolResult>; };
```

## Parameters

| Parameter        | Type   | Required | Meaning                                                                        |
| ---------------- | ------ | -------- | ------------------------------------------------------------------------------ |
| `query`          | string | No       | Autom name search.                                                             |
| `autom_group_id` | string | No       | Group filter. Use a known, supplied identifier; do not guess.                  |
| `type_id`        | string | No       | Type filter. No type-ID catalogue is exposed by this contract.                 |
| `page_size`      | number | No       | Requested page size; supported bounds are not specified in the exposed schema. |
| `cursor`         | string | No       | Pagination cursor. Reuse only the value returned by the preceding response.    |

## Minimal request

Replace the example search text with the intended Hyperflow name. It is a placeholder, not an identifier or an assertion that a flow exists.

```json
{
  "query": "<Hyperflow name to find>"
}
```

## Read the result

* Select the intended result using its returned name, type and trigger information. Preserve its returned `autom_id`; never invent an ID, reuse one from another environment or substitute a display name.
* If several results are plausible, ask the user to choose before inspecting or executing the wrong object.
* A `scope_note` can mean the search was limited to Hyperflows created by the connected user. An empty scoped result does not prove that the Hyperflow is absent from the platform.
* 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 discovery uses the connected workspace and caller's visible scope. If the read fails or is refused, resolve that error before interpreting the results. Do not turn an access failure into “no Hyperflows found.” Repeating a read does not execute a flow.

## 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: [`automs_get`](https://docs.autommate.com/userguide/mcp-and-ai-reference/tools/automs-get) · [`runs_search`](https://docs.autommate.com/userguide/mcp-and-ai-reference/tools/runs-search).
* 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).
