> 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/read-discovery-results-and-pagination.md).

# Read discovery results and pagination

Use returned identifiers, scope notes, and opaque cursors without assuming universal collection limits.

Discovery tools return identifiers for the next call. Read their visible labels for selection, then pass the returned identifier without rebuilding it from a name.

### Follow the returned cursor

A collection response can have this example shape:

{% code collapsedlinecount="10" %}

```json
{
  "items": [],
  "next_cursor": null,
  "total": 0
}
```

{% endcode %}

This is a shape illustration, not a live zero-result report. In actual non-empty responses, `items` contains the relevant records and `next_cursor` can be an opaque string. Follow that string unchanged with the same filters. Do not decode it, construct the next cursor, or reuse a cursor with a different query.

The search examples for Hyperflows, runs, libraries, actions, credentials, users and agents include total. The schedule example omits it. Treat total according to the selected tool’s returned contract.

### Choose a bounded page size

Dublin connector note: runs\_search.page\_size accepts values up to 50; larger values return INVALID\_ARGUMENT. Other tools may use different limits. A page\_size of 1 works in the collection examples, but their declarations do not publish every default or bound.

For libraries\_search, page\_size limits libraries; a returned library can contain multiple nested actions.

### Read each collection

| Tool                     | Observed item fields                                                                                                                | Important distinction                                                 |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `automs_search`          | `autom_id`, `name`, `description`, `status`, `type`, `trigger_type`, `active_version`, `group`, `updated_at`                        | Search matches names. Get the selected Autom before execution.        |
| `libraries_search`       | `library_name`, `library_label`, `module_label`, `action_count`, `installed`, `is_system`; a queried match also contained `actions` | An integration record is not an action input contract.                |
| `library_search_actions` | `action_ref`, `action_label`, `library_label`, `library_name`, `module_label`, `is_system`, `installed`                             | Use its `action_ref` with `library_get_action`.                       |
| `credentials_search`     | `credential_id`, `name`, `application_name`, `credential_type`, `status`, `is_default`, `owner`                                     | These are connection metadata, not secrets or a connectivity test.    |
| `users_search`           | `user_id`, `display_name`, `email`, `roles`, `status`                                                                               | `roles` was a string in the sampled response; do not assume an array. |

These fields describe response examples. Handle additional fields, omitted fields and null values according to the actual returned payload.

### Keep search scope with the result

Autom, credential, schedule, or run searches can be restricted to the caller's own objects. A `scope_note` describes that restriction. It is not proof that an object is missing from the entire tenant.

The user search excludes technicians according to the tool description. A missing row therefore does not prove that a person has no account.

The licensed action catalogue can omit restricted entries. Catalogue availability alone does not prove that a credential is valid, that the caller can use the action in every context, or that execution has succeeded.

### Practical discovery sequence

1. Search for the intended Autom or catalogue action.
2. Resolve ambiguity with the user when several records match.
3. Keep the returned `autom_id` or `action_ref`.
4. Read the detailed contract.
5. Collect missing input values before any authorized execution.

Discover identifiers in the active connection. Do not reuse remembered IDs from another environment; response examples do not supply a tenant domain.
