## Tool: `save_automation`

Validates and converts the generated automation to a Home APIs automation and persists it.

Don't retry if you encounter these errors: PERMISSION_DENIED, UNAUTHENTICATED, OUT_OF_RANGE, RESOURCE_EXHAUSTED, ALREADY_EXISTS. For other errors, retry at most three times.

The following code sample shows how to use `curl` to call the `save_automation` MCP tool.

| Curl Request |
|---|
| ```bash curl --location 'https://home.googleapis.com/mcp' \ --header 'Authorization: Bearer {oauth-access-token}' \ --header 'content-type: application/json' \ --header 'accept: application/json, text/event-stream' \ --data '{ "method": "tools/call", "params": { "name": "save_automation", "arguments": { // Provide these details according to the MCP tool specification. } }, "jsonrpc": "2.0", "id": 1 }' ``` |

## Input Schema

Request to insert or update an automation.

### UpsertAutomationRequest

| JSON representation |
|---|
| ``` { "automation": { object (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.Automation`) }, "idempotencyKey": string, // Union field `_active` can be only one of the following: "active": boolean // End of list of possible types for union field `_active`. } ``` |

| Fields ||
|---|---|
| `automation` | ``object (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.Automation`)`` Required. The automation to insert or update. For update operation, all fields in the automation will be updated by the specified automation. |
| `idempotencyKey` | `string` Optional. The idempotency key for the request, preventing duplicate automation creation and update operations. |
| Union field `_active`. `_active` can be only one of the following: ||
| `active` | `boolean` Optional. Whether the automation should be active or inactive. |
|   ||

### Automation

| JSON representation |
|---|
| ``` { "automationObjectId": string, "structureId": string, "name": string, "description": string, "clientMetadata": { string: string, ... }, "immediateExecution": boolean, "validState": enum (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.ValidState`), "activeState": enum (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.ActiveState`), "runningState": enum (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.RunningState`), // Union field `automation` can be only one of the following: "simpleAutomation": { object (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.SimpleAutomation`) } // End of list of possible types for union field `automation`. // Union field `_max_execution_count` can be only one of the following: "maxExecutionCount": integer // End of list of possible types for union field `_max_execution_count`. } ``` |

| Fields ||
|---|---|
| `automationObjectId` | `string` Required. Identifier. If automation_object_id is empty, it will create a new automation. If automation_object_id is provided, it will update the existing automation with the same object id. |
| `structureId` | `string` Required. The structure the automation belongs to. |
| `name` | `string` Optional. The name of the automation. If not provided, the system will generate one. If provided, the name should be unique within the structure. |
| `description` | `string` Optional. The generated description of the automation. |
| `clientMetadata` | `map (key: string, value: string (https://developers.google.com/discovery/v1/type-format format))` Optional. Metadata of an automation maintained by the clients. An object containing a list of `"key": value` pairs. Example: `{ "name": "wrench", "mass": "1.3kg", "count": "3" }`. |
| `immediateExecution` | `boolean` Optional. If true, the automation will be executed immediately after creation. |
| `validState` | ``enum (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.ValidState`)`` Output only. The valid state of the automation. |
| `activeState` | ``enum (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.ActiveState`)`` Output only. The active state of the automation. |
| `runningState` | ``enum (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.RunningState`)`` Output only. The running state of the automation. |
| Union field `automation`. The actual logic behind the automation. `automation` can be only one of the following: ||
| `simpleAutomation` | ``object (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.SimpleAutomation`)`` Optional. Simple automation with starters, conditions and actions. |
|   ||
| Union field `_max_execution_count`. `_max_execution_count` can be only one of the following: ||
| `maxExecutionCount` | `integer` Optional. Max execution count of the automation. If unset, the automation can execute an infinite number of times. If set to 0, the automation can execute zero times. |
|   ||

### SimpleAutomation

| JSON representation |
|---|
| ``` { "starters": [ { object (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.StarterBlock`) } ], "conditions": [ { object (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.ConditionBlock`) } ], "conditionsLogicalOperator": enum (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.LogicalOperator`), "actions": [ { object (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.ActionBlock`) } ] } ``` |

| Fields ||
|---|---|
| `starters[]` | ``object (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.StarterBlock`)`` Required. The starters of the automation. |
| `conditions[]` | ``object (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.ConditionBlock`)`` Optional. The conditions of the automation. |
| `conditionsLogicalOperator` | ``enum (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.LogicalOperator`)`` Optional. The logical operator to connect the conditions. |
| `actions[]` | ``object (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.ActionBlock`)`` Required. The actions of the automation. |

### StarterBlock

| JSON representation |
|---|
| ``` { "comparison": { object (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.Comparison`) }, "description": string, "starterDuration": string, // Union field `starter` can be only one of the following: "homeState": { object (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.HomeState`) }, "homeEvent": { object (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.HomeEvent`) } // End of list of possible types for union field `starter`. } ``` |

| Fields ||
|---|---|
| `comparison` | ``object (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.Comparison`)`` Optional. The comparison to compare the starter with the value. |
| `description` | `string` Optional. The description of the starter. |
| `starterDuration` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#duration` format)`` Optional. The duration for which the condition must be satisfied. A duration in seconds with up to nine fractional digits, ending with '`s`'. Example: `"3.5s"`. |
| Union field `starter`. The starter to compare. `starter` can be only one of the following: ||
| `homeState` | ``object (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.HomeState`)`` Optional. The home state to compare. |
| `homeEvent` | ``object (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.HomeEvent`)`` Optional. The home event to compare. |
|   ||

### HomeState

| JSON representation |
|---|
| ``` { "id": string, "type": string, "trait": string } ``` |

| Fields ||
|---|---|
| `id` | `string` Required. The id of the resource on which to reference the state. |
| `type` | `string` Required. The general type of the resource on which to execute the action on. |
| `trait` | `string` Required. The name of the uddm/whdm trait to reference. |

### HomeEvent

| JSON representation |
|---|
| ``` { "id": string, "type": string, "event": string, "parameters": { object } } ``` |

| Fields ||
|---|---|
| `id` | `string` Required. The id of the resource on which to reference the event. |
| `type` | `string` Required. The general type of the resource on which to execute the action on. |
| `event` | `string` Required. The name of the uddm/whdm event to reference. |
| `parameters` | ``object (`https://protobuf.dev/reference/protobuf/google.protobuf#struct` format)`` Optional. The parameters for the event, as a struct. |

### Struct

| JSON representation |
|---|
| ``` { "fields": { string: value, ... } } ``` |

| Fields ||
|---|---|
| `fields` | ``map (key: string, value: value (`https://protobuf.dev/reference/protobuf/google.protobuf#value` format))`` Unordered map of dynamically typed values. An object containing a list of `"key": value` pairs. Example: `{ "name": "wrench", "mass": "1.3kg", "count": "3" }`. |

### FieldsEntry

| JSON representation |
|---|
| ``` { "key": string, "value": value } ``` |

| Fields ||
|---|---|
| `key` | `string` |
| `value` | ``value (`https://protobuf.dev/reference/protobuf/google.protobuf#value` format)`` |

### Value

| JSON representation |
|---|
| ``` { // Union field `kind` can be only one of the following: "nullValue": null, "numberValue": number, "stringValue": string, "boolValue": boolean, "structValue": { object }, "listValue": array // End of list of possible types for union field `kind`. } ``` |

| Fields ||
|---|---|
| Union field `kind`. The kind of value. `kind` can be only one of the following: ||
| `nullValue` | `null` Represents a JSON `null`. |
| `numberValue` | `number` Represents a JSON number. Must not be `NaN`, `Infinity` or `-Infinity`, since those are not supported in JSON. This also cannot represent large Int64 values, since JSON format generally does not support them in its number type. |
| `stringValue` | `string` Represents a JSON string. |
| `boolValue` | `boolean` Represents a JSON boolean (`true` or `false` literal in JSON). |
| `structValue` | ``object (`https://protobuf.dev/reference/protobuf/google.protobuf#struct` format)`` Represents a JSON object. |
| `listValue` | ``array (`https://protobuf.dev/reference/protobuf/google.protobuf#list-value` format)`` Represents a JSON array. |
|   ||

### ListValue

| JSON representation |
|---|
| ``` { "values": [ value ] } ``` |

| Fields ||
|---|---|
| `values[]` | ``value (`https://protobuf.dev/reference/protobuf/google.protobuf#value` format)`` Repeated field of dynamically typed values. |

### Comparison

| JSON representation |
|---|
| ``` { "field": string, "operator": enum (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.ComparisonOperator`), "operands": [ { object (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.Operand`) } ] } ``` |

| Fields ||
|---|---|
| `field` | `string` Required. The field name of the state or event to compare. |
| `operator` | ``enum (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.ComparisonOperator`)`` Required. The operator to compare the state or event with the value. |
| `operands[]` | ``object (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.Operand`)`` Optional. The targets to compare the state or event with. |

### Operand

| JSON representation |
|---|
| ``` { // Union field `type` can be only one of the following: "value": value, "comparison": { object (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.Comparison`) } // End of list of possible types for union field `type`. } ``` |

| Fields ||
|---|---|
| Union field `type`. The value to compare the state or event with, or the nested comparison to compare the state or event with the nested value. `type` can be only one of the following: ||
| `value` | ``value (`https://protobuf.dev/reference/protobuf/google.protobuf#value` format)`` Optional. The value to compare the state or event with. |
| `comparison` | ``object (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.Comparison`)`` Optional. The nested comparison to compare the state or event with the nested value. |
|   ||

### Duration

| JSON representation |
|---|
| ``` { "seconds": string, "nanos": integer } ``` |

| Fields ||
|---|---|
| `seconds` | `string (https://developers.google.com/discovery/v1/type-format format)` Signed seconds of the span of time. Must be from -315,576,000,000 to +315,576,000,000 inclusive. Note: these bounds are computed from: 60 sec/min \* 60 min/hr \* 24 hr/day \* 365.25 days/year \* 10000 years |
| `nanos` | `integer` Signed fractions of a second at nanosecond resolution of the span of time. Durations less than one second are represented with a 0 `seconds` field and a positive or negative `nanos` field. For durations of one second or more, a non-zero value for the `nanos` field must be of the same sign as the `seconds` field. Must be from -999,999,999 to +999,999,999 inclusive. |

### ConditionBlock

| JSON representation |
|---|
| ``` { "homeState": { object (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.HomeState`) }, "comparison": { object (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.Comparison`) }, "description": string } ``` |

| Fields ||
|---|---|
| `homeState` | ``object (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.HomeState`)`` Required. The state to compare. |
| `comparison` | ``object (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.Comparison`)`` Required. The comparison to compare the state with the value. |
| `description` | `string` Optional. The description of the condition. |

### ActionBlock

| JSON representation |
|---|
| ``` { "description": string, // Union field `action` can be only one of the following: "homeAction": { object (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.HomeAction`) }, "delay": { object (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.Delay`) } // End of list of possible types for union field `action`. } ``` |

| Fields ||
|---|---|
| `description` | `string` Optional. The description of the action block. |
| Union field `action`. The action to execute. `action` can be only one of the following: ||
| `homeAction` | ``object (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.HomeAction`)`` Optional. The home action to execute. |
| `delay` | ``object (`https://developers.home.google.com/reference/home/mcp/tools_list/list_automations#Output.Schema.Delay`)`` Optional. The delay to execute the action. |
|   ||

### HomeAction

| JSON representation |
|---|
| ``` { "id": string, "type": string, "command": string, "parameters": { object } } ``` |

| Fields ||
|---|---|
| `id` | `string` Required. The id of the resource on which to execute the action on. |
| `type` | `string` Required. The general type of the resource on which to execute the action on. |
| `command` | `string` Required. The name of the uddm/whdm command to execute. |
| `parameters` | ``object (`https://protobuf.dev/reference/protobuf/google.protobuf#struct` format)`` Optional. The parameters for the action, as a struct. |

### Delay

| JSON representation |
|---|
| ``` { "duration": string } ``` |

| Fields ||
|---|---|
| `duration` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#duration` format)`` Required. The delay duration in seconds. A duration in seconds with up to nine fractional digits, ending with '`s`'. Example: `"3.5s"`. |

### ClientMetadataEntry

| JSON representation |
|---|
| ``` { "key": string, "value": string } ``` |

| Fields ||
|---|---|
| `key` | `string` |
| `value` | `string (https://developers.google.com/discovery/v1/type-format format)` A base64-encoded string. |

### NullValue

Represents a JSON `null`.

`NullValue` is a sentinel, using an enum with only one value to represent the null value for the `Value` type union.

A field of type `NullValue` with any value other than `0` is considered invalid. Most ProtoJSON serializers will emit a `Value` with a `null_value` set as a JSON `null` regardless of the integer value, and so will round trip to a `0` value.

| Enums ||
|---|---|
| `NULL_VALUE` | Null value. |

### ComparisonOperator

The operator to compare the state or event with the value.

| Enums ||
|---|---|
| `COMPARISON_OPERATOR_UNSPECIFIED` | Unspecified operator. |
| `EQUALS` | The operator is equals. |
| `NOT_EQUALS` | The operator is not equals. |
| `LESS_THAN` | The operator is less than. |
| `LESS_THAN_EQUALS` | The operator is less than or equals. |
| `GREATER_THAN` | The operator is greater than. |
| `GREATER_THAN_EQUALS` | The operator is greater than or equals. |
| `ANY_MATCH` | The operator is any match. |
| `BETWEEN` | The operator is between. |
| `IS_IN` | The operator is is in. |

### LogicalOperator

The logical operator to connect the starters.

| Enums ||
|---|---|
| `LOGICAL_OPERATOR_UNSPECIFIED` | Unspecified logical operator. |
| `LOGICAL_OPERATOR_AND` | The logical operator is AND. |
| `LOGICAL_OPERATOR_OR` | The logical operator is OR. |

### ValidState

The valid state of the automation.

| Enums ||
|---|---|
| `VALID_STATE_UNSPECIFIED` | Unspecified valid state. |
| `VALID` | Automation is valid and can be activated. |
| `INVALID` | Automation is invalid. |

### ActiveState

The active state of the automation.

| Enums ||
|---|---|
| `ACTIVE_STATE_UNSPECIFIED` | Unspecified active state. |
| `ACTIVE` | Automation is active. |
| `INACTIVE` | Automation is inactive. |

### RunningState

The running state of the automation.

| Enums ||
|---|---|
| `RUNNING_STATE_UNSPECIFIED` | Unspecified running state. |
| `RUNNING` | Automation is running. |
| `NOT_RUNNING` | Automation is not running. |

## Output Schema

Response for UpsertAutomation.

### Tool Annotations


[Tool annotations](https://modelcontextprotocol.io/specification/latest/schema#toolannotations) are sent to MCP clients to describe the basic risk of a given tool. Most clients treat these hints as untrusted, but they can be used to decide when a confirmation prompt might be sent to a user.


Along with the title string, the following boolean hints are defined as follows:

- `readOnlyHint`: If true, the tool doesn't modify its environment. Default: false.
- `destructiveHint`: If true, then the tool can perform destructive actions. If false, then the tool can only perform additive actions. Default: true.
- `idempotentHint`: If true, then calling the tool repeatedly with the same arguments will have no additional effect on its environment. Default: false.
- `openWorldHint`: If true, then the tool can interact with an 'open world' of external entities. If false, then the tool can only interact with internal entities. For example, a web search tool would be open world, while a memory tool would not be open world.

Destructive Hint: ✅ \| Idempotent Hint: ❌ \| Read Only Hint: ❌ \| Open World Hint: ✅