MCP Tools Reference: home.googleapis.com

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
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 (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 (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 (ValidState),
  "activeState": enum (ActiveState),
  "runningState": enum (RunningState),

  // Union field automation can be only one of the following:
  "simpleAutomation": {
    object (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 (bytes 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 (ValidState)

Output only. The valid state of the automation.

activeState

enum (ActiveState)

Output only. The active state of the automation.

runningState

enum (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 (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 (StarterBlock)
    }
  ],
  "conditions": [
    {
      object (ConditionBlock)
    }
  ],
  "conditionsLogicalOperator": enum (LogicalOperator),
  "actions": [
    {
      object (ActionBlock)
    }
  ]
}
Fields
starters[]

object (StarterBlock)

Required. The starters of the automation.

conditions[]

object (ConditionBlock)

Optional. The conditions of the automation.

conditionsLogicalOperator

enum (LogicalOperator)

Optional. The logical operator to connect the conditions.

actions[]

object (ActionBlock)

Required. The actions of the automation.

StarterBlock

JSON representation
{
  "comparison": {
    object (Comparison)
  },
  "description": string,
  "starterDuration": string,

  // Union field starter can be only one of the following:
  "homeState": {
    object (HomeState)
  },
  "homeEvent": {
    object (HomeEvent)
  }
  // End of list of possible types for union field starter.
}
Fields
comparison

object (Comparison)

Optional. The comparison to compare the starter with the value.

description

string

Optional. The description of the starter.

starterDuration

string (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 (HomeState)

Optional. The home state to compare.

homeEvent

object (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 (Struct format)

Optional. The parameters for the event, as a struct.

Struct

JSON representation
{
  "fields": {
    string: value,
    ...
  }
}
Fields
fields

map (key: string, value: value (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 (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 (Struct format)

Represents a JSON object.

listValue

array (ListValue format)

Represents a JSON array.

ListValue

JSON representation
{
  "values": [
    value
  ]
}
Fields
values[]

value (Value format)

Repeated field of dynamically typed values.

Comparison

JSON representation
{
  "field": string,
  "operator": enum (ComparisonOperator),
  "operands": [
    {
      object (Operand)
    }
  ]
}
Fields
field

string

Required. The field name of the state or event to compare.

operator

enum (ComparisonOperator)

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

operands[]

object (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 (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 (Value format)

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

comparison

object (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 (int64 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 (HomeState)
  },
  "comparison": {
    object (Comparison)
  },
  "description": string
}
Fields
homeState

object (HomeState)

Required. The state to compare.

comparison

object (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 (HomeAction)
  },
  "delay": {
    object (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 (HomeAction)

Optional. The home action to execute.

delay

object (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 (Struct format)

Optional. The parameters for the action, as a struct.

Delay

JSON representation
{
  "duration": string
}
Fields
duration

string (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 (bytes 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 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: ✅