> 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/discovery-tool-contracts.md).

# Discovery tool contracts

**Direct tool references:** [`automs_search`](https://docs.autommate.com/userguide/mcp-and-ai-reference/tools/automs-search.md) · [`libraries_search`](https://docs.autommate.com/userguide/mcp-and-ai-reference/tools/libraries-search.md) · [`library_search_actions`](https://docs.autommate.com/userguide/mcp-and-ai-reference/tools/library-search-actions.md) · [`credentials_search`](https://docs.autommate.com/userguide/mcp-and-ai-reference/tools/credentials-search.md) · [`users_search`](https://docs.autommate.com/userguide/mcp-and-ai-reference/tools/users-search.md). These pages describe the discovery/inspection subset of the current tool inventory, with declarations reviewed on 21 October 2026. Check [capabilities and version scope](https://docs.autommate.com/userguide/mcp-and-ai-reference/capabilities-and-version-scope.md) for the active connection.

Use discovery tools to find identifiers and determine the visible scope before retrieving details or requesting execution. Tool names below are the logical MCP names; an AI client may add a namespace prefix.

Omit optional parameters you do not need. Use only declared filters and identifiers. Dublin connector note: runs\_search.page\_size accepts values up to 50; larger values return INVALID\_ARGUMENT. Other tools may have different limits. See [Read discovery results and pagination](https://docs.autommate.com/userguide/mcp-and-ai-reference/read-discovery-results-and-pagination.md).

### Inventory by task

| Group    | Tools                                                                                               | Purpose                                                                                                      |
| -------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Discover | `automs_search`, `libraries_search`, `library_search_actions`, `credentials_search`, `users_search` | Find accessible records and valid identifiers.                                                               |
| Read     | `automs_get`, `library_get_action`, `platform_get_summary`, `agents_get_health`, `schedules_search` | Inspect inputs, configuration, scope, or operational evidence.                                               |
| Run      | `automs_run`                                                                                        | Start an existing supported Autom. This changes the environment.                                             |
| Monitor  | `runs_search`, `runs_get`, `runs_get_latest_error`                                                  | Read execution status and evidence after a run. There is no dedicated wait or resume tool in this inventory. |

### `automs_search`

Search Hyperflow names with automs\_search. The query matches names, not descriptions. Pass a returned autom\_id to subsequent calls; resolve ambiguous names before reading or running a Hyperflow.

| 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.    |

Preserve scope\_note when results are restricted to Hyperflows created by the connected user. An absent match then means the object is not visible in that scope.

### `libraries_search`

Browse licensed integration libraries. With no query, the tool lists libraries. A query returns matching libraries with their actions. Use the separate action-search tool when looking for an action across libraries.

| Parameter   | Type   | Required | Meaning                     |
| ----------- | ------ | -------- | --------------------------- |
| `query`     | string | No       | Library/application search. |
| `page_size` | number | No       | Requested page size.        |
| `cursor`    | string | No       | Returned pagination cursor. |

### `library_search_actions`

Search actions in the licensed catalogue. The search matches whole words in labels. Browse the relevant application with `libraries_search` when its catalogue structure is unclear.

| Parameter     | Type   | Required | Meaning                     |
| ------------- | ------ | -------- | --------------------------- |
| `application` | string | No       | Application filter.         |
| `query`       | string | No       | Action label search.        |
| `page_size`   | number | No       | Requested page size.        |
| `cursor`      | string | No       | Returned pagination cursor. |

Pass the returned action\_ref to library\_get\_action. Action labels are display text, not identifiers. The licensed catalogue omits restricted entries, so searches reflect the caller’s available integrations.

### `credentials_search`

Find stored application-connection metadata. The result can describe a connection's name, application, and active flag. It does **not** return secrets and does **not** test connectivity.

| Parameter     | Type                   | Required | Meaning                      |
| ------------- | ---------------------- | -------- | ---------------------------- |
| `application` | string                 | No       | Application filter.          |
| `query`       | string                 | No       | Connection search.           |
| `status`      | `active` or `inactive` | No       | Stored-record status filter. |
| `page_size`   | number                 | No       | Requested page size.         |
| `cursor`      | string                 | No       | Returned pagination cursor.  |

The active flag describes stored credential metadata, not a destination authentication test. Retain any scope\_note restricting results to the caller’s credentials. Use runs\_get\_latest\_error to investigate a related execution failure.

### `users_search`

Find tenant user-account metadata. The query searches names and email addresses. This is not a sales-contact directory or an activity-history tool. Technician accounts are excluded by this tool's contract.

| 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.                                       |

A refusal means the caller lacks access; it is not an empty directory. A missing row does not prove the person has no account.

### Pagination and response interpretation

* Treat cursors as opaque. Follow the returned continuation information without editing or guessing cursor values.
* Keep the original filters consistent while paging through a result set.
* Stop when the response indicates there are no further pages. Do not assume the first page is the full inventory.
* Record the time and permission scope of the read when using it as documentation evidence.

Collection examples use items and next\_cursor. Some also include total; schedules\_search examples do not. Parse the fields returned by the selected tool rather than requiring one universal collection shape. See [Read discovery results and pagination](https://docs.autommate.com/userguide/mcp-and-ai-reference/read-discovery-results-and-pagination.md).

### Worked example: find the documented request-intake flow

Goal: identify an existing Hyperflow and prepare a read-only inspection. Start after your client has connected to the intended workspace and completed the authorization supported by that client. This exercise does not test OAuth setup or execute the flow.

The Build a Hyperflow walkthrough uses the name Docs - Request intake - 20261013. Use that name only if the example exists in your connected workspace; otherwise use the exact name of your own test Hyperflow. Do not copy its internal ID from a screenshot or another environment.

#### 1. Search by the flow name

Call automs\_search with these example arguments:

{% code collapsedlinecount="20" %}

```json
{
  "query": "Docs - Request intake - 20261013",
  "page_size": 5
}
```

{% endcode %}

Read each returned item’s name, type, trigger\_type and autom\_id. Search matches the name, not a description. A result with a similar label is not enough when several flows match.

#### 2. Resolve the selection before continuing

One confirmed match: keep its returned autom\_id. Several plausible matches: ask which one to inspect, using the available labels and context. No visible match: check the exact name, current workspace and any scope\_note. An empty scoped result does not prove the flow is absent from the whole platform.

If next\_cursor is present and more results are needed, repeat the same search with the returned cursor unchanged. Do not manufacture a cursor or change the filters halfway through pagination.

#### 3. Read the selected flow

Call automs\_get. Replace the placeholder below with the autom\_id returned by your search; it is not a reusable example ID.

{% code collapsedlinecount="20" %}

```json
{
  "autom_id": "<autom_id returned by automs_search>",
  "include_flow": false
}
```

{% endcode %}

Record the selected name, ID, version, trigger and declared input contract. input\_contract: \[] means declared empty inputs after a successful read. inputs\_note without input\_contract means the input contract is unknown, so the agent must ask or inspect further rather than supply an empty object.

Completion check: a human or AI agent can identify exactly which existing flow was inspected and what is known about its inputs. Nothing has been created, released, deployed or run. To explain the flow logic, continue with Inspection tool contracts and request include\_flow: true.

## Build a service from verified context

* [Build a service with an AI assistant](https://docs.autommate.com/userguide/mcp-and-ai-reference/structured-service-authoring) — outcome, native components, Govern/Execute/Prove and a controlled lifecycle.
* [Resolve deployment inputs](https://docs.autommate.com/userguide/mcp-and-ai-reference/deployment-input-resolution) — reuse valid context, Engage payloads and earlier Work Item outputs; ask only for unresolved decisions.
* [Discover native apps, triggers and Data Manager](https://docs.autommate.com/userguide/mcp-and-ai-reference/native-app-trigger-and-data-discovery) — find the installed component and its exact contract before building a custom alternative.
