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

# Inspection tool contracts

**Direct tool references:** [`automs_get`](https://docs.autommate.com/userguide/mcp-and-ai-reference/tools/automs-get.md) · [`library_get_action`](https://docs.autommate.com/userguide/mcp-and-ai-reference/tools/library-get-action.md) · [`platform_get_summary`](https://docs.autommate.com/userguide/mcp-and-ai-reference/tools/platform-get-summary.md) · [`agents_get_health`](https://docs.autommate.com/userguide/mcp-and-ai-reference/tools/agents-get-health.md) · [`schedules_search`](https://docs.autommate.com/userguide/mcp-and-ai-reference/tools/schedules-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.

Read the selected object's contract before interpreting it or taking an action. Configuration, connection health, execution status, and the final business result answer different questions.

### `automs_get`

Read a Hyperflow’s metadata and run-input contract with an autom\_id returned by automs\_search.

| Parameter      | Type    | Required | Meaning                                                                                               |
| -------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `autom_id`     | string  | Yes      | Identifier returned by `automs_search`.                                                               |
| `include_flow` | boolean | No       | Include the readable flow outline. Default is `false`; use `true` when explaining what an Autom does. |

#### Documented response semantics

| Field or condition                           | Meaning                                                                                                                                  |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `input_contract: []` after a successful read | No declared run inputs.                                                                                                                  |
| `inputs_note` without `input_contract`       | Input requirements are unknown; ask the user what must be supplied. Do not treat this as no inputs.                                      |
| `flow_outline` when `include_flow: true`     | Readable text outline; observed as a string.                                                                                             |
| `flow_tree` when `include_flow: true`        | Observed as an array of records with `caption`, and optional `kind` and nested `children`. It is not a guaranteed diagram-format string. |
| `flow_summary` when `include_flow: true`     | Flow summary; observed as a string.                                                                                                      |
| `flow_stats` when `include_flow: true`       | Observed object with `step_count`, `branch_count`, `error_handling_steps`, and `systems`.                                                |

The flow view is not raw editable flow JSON and does not return field values. Do not infer missing or masked values. The tool also exposes a schedule summary; next-run information belongs to `schedules_search`.

Read the returned input\_contract before building the inputs object. The Hyperflow input example does not include is\_required, whereas the catalogue action example does. Do not transfer requiredness rules between those contracts. See [Read Hyperflow and action input contracts](https://docs.autommate.com/userguide/mcp-and-ai-reference/read-hyperflow-and-action-input-contracts.md).

### `library_get_action`

Read the declared inputs of a catalogue action. Use `action_ref` from `library_search_actions`, not an action's label.

| Parameter    | Type   | Required | Meaning                                         |
| ------------ | ------ | -------- | ----------------------------------------------- |
| `action_ref` | string | Yes      | Reference returned by `library_search_actions`. |

`inputs: []` means the action declares no inputs. `inputs_note` without `inputs` means the definition is unknown. An action definition is catalogue information; reading it neither inserts the action into a flow nor executes the action.

### `platform_get_summary`

Read an operational summary for the connected tenant.

| Parameter | Type                  | Required | Meaning                                                            |
| --------- | --------------------- | -------- | ------------------------------------------------------------------ |
| `window`  | `24h`, `7d`, or `30d` | No       | Reporting window. The exposed schema does not specify the default. |

Select the summary window explicitly when comparing periods. Use a specific run record to answer whether an individual request completed.

### `agents_get_health`

Read Mate Agent host health from recent metrics.

| Parameter    | Type    | Required | Meaning                                                                                                                   |
| ------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
| `live_check` | boolean | No       | Request a live reachability probe. Without that probe, interpret health as recent metrics rather than a live socket test. |
| `page_size`  | number  | No       | Requested page size; no bounds or default are published in the exposed schema.                                            |
| `cursor`     | string  | No       | Returned pagination cursor.                                                                                               |

Agent health describes execution hosts. Check run records for outcomes and destination responses for authentication. Retain scope information because shared deployments can list agents outside the connected tenant.

### `schedules_search`

Read running schedules and their next-run time.

| Parameter   | Type                           | Required | Meaning                                                                                         |
| ----------- | ------------------------------ | -------- | ----------------------------------------------------------------------------------------------- |
| `query`     | string                         | No       | Schedule/Autom search value. Exact matching rules are not specified in the exposed description. |
| `sort_by`   | `autom_name` or `scheduled_at` | No       | Sort field.                                                                                     |
| `page_size` | number                         | No       | Requested page size.                                                                            |
| `cursor`    | string                         | No       | Returned pagination cursor.                                                                     |

Paused and disabled schedules do not appear in this result. Read the Autom's schedule summary and running state with `automs_get` when investigating an absent schedule. Recurrence detail is also on `automs_get`, not this search tool.

A `scope_note` may restrict results to Automs created by the connected user. Report that restriction instead of stating that no schedules exist across the environment.

### What this inventory does not provide

The inspection tools on this page read existing objects. Separate tools such as `automs_get_flow`, `automs_edit_flow`, `services_create` and deployment tools address authoring and deployment on connections that advertise them. Use the current tool index and exact request schema; an inspection result does not authorize a write.

### Worked example: inspect the String Assign contract before mapping it

The beginner Hyperflow prepares a synthetic request summary using String → Assign. This exercise shows how an AI agent can inspect the installed action’s contract before recommending a mapping. It reads catalog metadata; it does not add an action to a canvas or execute it.

#### 1. Discover the catalog action

Call library\_search\_actions with a whole-word query:

{% code collapsedlinecount="20" %}

```json
{
  "query": "Assign",
  "page_size": 5
}
```

{% endcode %}

Several data-type libraries can expose an Assign action. Select the returned record whose library\_label and action\_label identify the intended String action. If it is not on the first page, use the returned next\_cursor with the same query. The catalog is license-scoped; an omitted action is not proof that the product has no such action.

#### 2. Read the declared fields

Pass only the selected action\_ref returned by that search:

{% code collapsedlinecount="20" %}

```json
{
  "action_ref": "<action_ref returned for String Assign>"
}
```

{% endcode %}

Inspect each returned input’s name, display name, type, required/masked flags and default when those fields are supplied. Preserve the machine name for programmatic interpretation and use the display label when explaining the editor. Do not infer a missing field or a required flag that was not returned.

#### 3. Compare the contract with the worked example

In the current UI walkthrough, Value to Assign contains REQ-DEMO-001 | VPN access | Maya Chen and Source to be Assigned selects the String output variable request\_summary. The latter is the receiving variable despite its label. Compare those controls with the installed catalog contract rather than guessing a JSON key from the visible label.

The expected local value is the same fixed request summary. A catalog read does not prove that the assignment ran; the walkthrough’s Inspector/run evidence performs that separate check.

#### 4. Keep three contracts distinct

The library\_get\_action inputs describe how that catalog action is configured. The automs\_get input\_contract describes inputs accepted when running an existing Hyperflow. The flow’s returned data describes its result. Do not send every action configuration field to automs\_run as if it were a declared flow input.

Completion check: the selected action\_ref is traced to the search, the input names/types come from the returned contract, and any configuration or execution work remains a separate step. Use the separately advertised authoring and deployment tools for changes, with their own schemas and permissions.

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