MCP Tools Reference: home.googleapis.com

Tool: list_home_resources

Retrieves a list of home resources including devices. This is the primary tool for discovering what resources are available.

The following code sample shows how to use curl to call the list_home_resources 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": "list_home_resources",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Input Schema

Request for DiscoverHomeResources.

DiscoverHomeResourcesRequest

JSON representation 
{
  "structureId": string,
  "view": enum (ResourceView),
  "filter": {
    object (Filter)
  },
  "pageSize": integer,
  "pageToken": string
}
Fields
structureId

string

Optional. The HomeGraph structure_id to filter devices by. If omitted, resources from all structures for the user will be discovered.
view

enum (ResourceView)

Optional. The view to apply to the returned resources.
filter

object (Filter)

Optional. An optional search filter for the resource metadata. When any of the fields match, the resource is returned.
pageSize

integer

Optional. The maximum number of devices to return. The service may return fewer than this value.
pageToken

string

Optional. A page token, received from a previous DiscoverHomeResources call. Provide this to retrieve the subsequent page.

Filter

JSON representation 
{
  "resourceIds": [
    string
  ],
  "shortenedResourceTypes": [
    string
  ],
  "shortenedResourceTraits": [
    string
  ],
  "shortenedResourceEvents": [
    string
  ],
  "fieldPaths": [
    string
  ]
}
Fields
resourceIds[]

string

Optional. The resource id for filtering. (e.g. device@device_id, automation@automation_id)
shortenedResourceTypes[]

string

Optional. The resource types to filter resources by. Example: "GoogleLightDevice", "GoogleDisplayDevice", "SpeakerDevice", "VideoRemoteControlDevice" (and not "action.devices.types.LIGHT"). Not case sensitive.
shortenedResourceTraits[]

string

Optional. The resource traits to filter resources by. Component prefixes should not be included and should be specified in the shortened_resource_types field instead. Example: "OnOff", "Volume" (and not either "home.uddm.traits.matter.OnOffTrait" or "GoogleTvDevice/OnOff"). Not case sensitive.
shortenedResourceEvents[]

string

Optional. The resource events to filter history events by. Must be in "TraitName.EventName" format (e.g. CameraHistory.HistoryItem). Should not be prefixed by component name. Not case sensitive.
fieldPaths[]

string

Optional. Paths to filter by. These are case sensitive. Traits and events should be properly PascalCased and fields should be camelCased.

Format: - For traits: "[Trait].[fieldPath]" - For events: "[Trait].[Event].[fieldPath]"

Examples: - "OnOff.onOff" (or "OnOff.state.onOff") - "CameraHistory.HistoryItem.eventTracks.zones"

For the path filter to take effect, the trait or event type must also be specified in shortened_resource_traits or shortened_resource_events respectively.

ResourceView

An enum to control the level of detail in resource responses.

Enums
RESOURCE_VIEW_UNSPECIFIED Default value, will be treated as VIEW_SUMMARY.
VIEW_SUMMARY Includes all fields except for the volatile states field. Useful for high-level lists and dashboards where current state isn't needed.
VIEW_FULL Includes all fields, including the complete states map. Useful when you need to know the exact current state before acting on a device.
VIEW_FULL_WITH_AUTOMATION_GENERATION Includes all fields, including the complete states map with all automation traits (e.g., Time). This view MUST be used when discovering resources for the purpose of creating or generating automations. Does not include unstructured devices.

Output Schema

Response for DiscoverHomeResources.

DiscoverHomeResourcesResponse

JSON representation 
{
  "resources": [
    {
      object (Resource)
    }
  ],
  "resourceMetadata": [
    {
      object (ResourceMetadata)
    }
  ],
  "nextPageToken": string
}
Fields
resources[]

object (Resource)

The list of home resources.
resourceMetadata[]

object (ResourceMetadata)

The metadata for the home resources.
nextPageToken

string

The next page token to use for the next request.

Resource

JSON representation 
{
  "id": string,
  "type": string,
  "supportedTraits": [
    string
  ],
  "displayName": string,
  "parentIds": [
    string
  ],
  "metadataId": string,
  "resourceInfo": {
    object (ResourceInfo)
  },
  "isPart": boolean
}
Fields
id

string

Identifier. The unique identifier of the resource.
type

string

Output only. The type of the resource.
supportedTraits[]

string

Output only. A list of all traits this resource supports.
displayName

string

Output only. The user-friendly, mutable name of the resource.
parentIds[]

string

Output only. A list of all resource ids this resource is a member of.
metadataId

string

Output only. The metadata id for this resource.
resourceInfo

object (ResourceInfo)

Output only. Metadata about the device hardware and software.
isPart

boolean

Output only. True if this resource is part of a multi-faceted device.

ResourceInfo

JSON representation 
{

  // Union field resource_info can be only one of the following:
  "deviceInfo": {
    object (DeviceInfo)
  },
  "structureInfo": {
    object (StructureInfo)
  }
  // End of list of possible types for union field resource_info.
}
Fields
Union field resource_info. The type of resource this metadata is for. resource_info can be only one of the following:
deviceInfo

object (DeviceInfo)

Output only. Metadata about the device.
structureInfo

object (StructureInfo)

Output only. Metadata about the structure.

DeviceInfo

JSON representation 
{
  "vendorName": string,
  "productName": string,
  "hardwareVersionString": string,
  "softwareVersionString": string
}
Fields
vendorName

string

Output only. The name of the manufacturer/vendor of the resource.
productName

string

Output only. The model/product name of the resource.
hardwareVersionString

string

Output only. The hardware version of the resource.
softwareVersionString

string

Output only. The software version of the resource.

StructureInfo

JSON representation 
{
  "timeZone": string,
  "address": string,
  "temperatureUnit": string
}
Fields
timeZone

string

Output only. The time zone of the structure.
address

string

Output only. The address of the structure.
temperatureUnit

string

Output only. The preferred temperature unit of the structure (e.g. "CELSIUS", "FAHRENHEIT").

ResourceMetadata

JSON representation 
{
  "id": string,
  "type": string,
  "traits": {
    string: {
      object (TraitDefinition)
    },
    ...
  }
}
Fields
id

string

Output only. The unique identifier of the resource metadata.
type

string

Output only. The type of resource this metadata is for.
traits

map (key: string, value: object (TraitDefinition))

Output only. A map of all functional traits this resource supports. The key is the normalized trait name (e.g., "OnOff", "Brightness").

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

TraitsEntry

JSON representation 
{
  "key": string,
  "value": {
    object (TraitDefinition)
  }
}
Fields
key

string
value

object (TraitDefinition)

TraitDefinition

JSON representation 
{
  "description": string,
  "uddmDeviceTypes": [
    string
  ],
  "resourceTypes": [
    string
  ],
  "states": {
    string: {
      object (ParameterDefinition)
    },
    ...
  },
  "commands": {
    string: {
      object (CommandDefinition)
    },
    ...
  },
  "events": {
    string: {
      object (EventDefinition)
    },
    ...
  },
  "experimental": boolean
}
Fields
description

string

Output only. The description of the trait.
uddmDeviceTypes[]

string

Output only. The UDDM device types that this trait is applicable to.
resourceTypes[]

string

Output only. The resource types that this trait is applicable to.
states

map (key: string, value: object (ParameterDefinition))

Output only. The states of the trait. Key: state name (e.g., "onOff", "brightness")

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
commands

map (key: string, value: object (CommandDefinition))

Output only. The commands of the trait. Key: command name (e.g., "onOff", "brightness")

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
events

map (key: string, value: object (EventDefinition))

Output only. The events of the trait. Key: event name (e.g., "onOffChange", "brightnessChange")

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
experimental

boolean

Output only. Whether the trait is experimental.

StatesEntry

JSON representation 
{
  "key": string,
  "value": {
    object (ParameterDefinition)
  }
}
Fields
key

string
value

object (ParameterDefinition)

ParameterDefinition

JSON representation 
{
  "description": string,
  "required": boolean,
  "unit": string,
  "unitScale": number,

  // Union field parameter_type can be only one of the following:
  "booleanParameter": {
    object (BooleanParameter)
  },
  "numberParameter": {
    object (NumberParameter)
  },
  "stringParameter": {
    object (StringParameter)
  },
  "structParameter": {
    object (StructParameter)
  },
  "listParameter": {
    object (ParameterDefinition)
  },
  "bitmapParameter": {
    object (BitmapParameter)
  }
  // End of list of possible types for union field parameter_type.
}
Fields
description

string

Output only. The description of the parameter.
required

boolean

Output only. Whether the parameter is required.
unit

string

Output only. The unit of the parameter, e.g. "C" for Celsius, "%" for percentage, etc.
unitScale

number

Output only. The scale of the parameter, e.g. 0.01 for percentage, etc.
Union field parameter_type. The type of the parameter. parameter_type can be only one of the following:
booleanParameter

object (BooleanParameter)

Output only. The parameter is a boolean.
numberParameter

object (NumberParameter)

Output only. The parameter is a number.
stringParameter

object (StringParameter)

Output only. The parameter is a string.
structParameter

object (StructParameter)

Output only. The parameter is a struct.
listParameter

object (ParameterDefinition)

Output only. The parameter is a list of the same type of elements.
bitmapParameter

object (BitmapParameter)

Output only. The parameter is a bitmap.

NumberParameter

JSON representation 
{
  "numberType": enum (NumberType),

  // Union field constraint can be only one of the following:
  "allowedRange": {
    object (RangeConstraint)
  },
  "allowedValues": {
    object (ValuesConstraint)
  }
  // End of list of possible types for union field constraint.
}
Fields
numberType

enum (NumberType)

Output only. The type of the number parameter, which can be an integer or a floating point number.
Union field constraint. The constraint on the number parameter, if any. constraint can be only one of the following:
allowedRange

object (RangeConstraint)

Output only. The range of values that the parameter can be.
allowedValues

object (ValuesConstraint)

Output only. The list of values that the parameter can be.

RangeConstraint

JSON representation 
{
  "min": number,
  "max": number
}
Fields
min

number

Output only. The minimum value of the range.
max

number

Output only. The maximum value of the range.

ValuesConstraint

JSON representation 
{
  "values": [
    {
      object (ValueConstraint)
    }
  ]
}
Fields
values[]

object (ValueConstraint)

Output only. The list of values that the parameter can be.

ValueConstraint

JSON representation 
{
  "value": number,
  "synonyms": [
    string
  ]
}
Fields
value

number

Output only. The value allowed for the parameter.
synonyms[]

string

Output only. Users may refer to this value by these synonyms.

StringParameter

JSON representation 
{
  "allowedValues": [
    {
      object (ValueConstraint)
    }
  ]
}
Fields
allowedValues[]

object (ValueConstraint)

Output only. The list of allowed values for the parameter, if empty, the parameter can be any string.

ValueConstraint

JSON representation 
{
  "value": string,
  "synonyms": [
    string
  ]
}
Fields
value

string

Output only. The value allowed for the parameter.
synonyms[]

string

Output only. Users may refer to this value by these synonyms.

StructParameter

JSON representation 
{
  "fields": {
    string: {
      object (ParameterDefinition)
    },
    ...
  }
}
Fields
fields

map (key: string, value: object (ParameterDefinition))

Output only. The fields of the struct.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

FieldsEntry

JSON representation 
{
  "key": string,
  "value": {
    object (ParameterDefinition)
  }
}
Fields
key

string
value

object (ParameterDefinition)

BitmapParameter

JSON representation 
{
  "combinedBits": [
    {
      object (CombinedBitsDescriptor)
    }
  ],
  "typeId": string
}
Fields
combinedBits[]

object (CombinedBitsDescriptor)

Output only. The list of combined bits.
typeId

string

Output only. The type id of the bitmap constraint.

CombinedBitsDescriptor

JSON representation 
{
  "bitPositionStart": integer,
  "bitPositionEnd": integer,
  "name": string
}
Fields
bitPositionStart

integer

Output only. The starting bit position of the combined bits.
bitPositionEnd

integer

Output only. The ending bit position of the combined bits.
name

string

Output only. The name of the combined bits.

CommandsEntry

JSON representation 
{
  "key": string,
  "value": {
    object (CommandDefinition)
  }
}
Fields
key

string
value

object (CommandDefinition)

CommandDefinition

JSON representation 
{
  "description": string,
  "sensitivityLevel": enum (SensitivityLevel),
  "parameters": {
    string: {
      object (ParameterDefinition)
    },
    ...
  }
}
Fields
description

string

Output only. The description of the command.
sensitivityLevel

enum (SensitivityLevel)

Output only. The sensitivity level of the command.
parameters

map (key: string, value: object (ParameterDefinition))

Output only. The parameters of the command. Key: parameter name (e.g., "level", "color")

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

ParametersEntry

JSON representation 
{
  "key": string,
  "value": {
    object (ParameterDefinition)
  }
}
Fields
key

string
value

object (ParameterDefinition)

EventsEntry

JSON representation 
{
  "key": string,
  "value": {
    object (EventDefinition)
  }
}
Fields
key

string
value

object (EventDefinition)

EventDefinition

JSON representation 
{
  "description": string,
  "parameters": {
    string: {
      object (ParameterDefinition)
    },
    ...
  }
}
Fields
description

string

Output only. The description of the event.
parameters

map (key: string, value: object (ParameterDefinition))

Output only. The parameters of the event. Key: parameter name (e.g., "level", "color")

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

ParametersEntry

JSON representation 
{
  "key": string,
  "value": {
    object (ParameterDefinition)
  }
}
Fields
key

string
value

object (ParameterDefinition)

NumberType

The type of the number parameter.

Enums
NUMBER_TYPE_UNSPECIFIED If unspecified, the parameter will be treated as NUMBER_TYPE_NUMBER.
NUMBER_TYPE_INTEGER The parameter is an integer.
NUMBER_TYPE_NUMBER The parameter is a floating point number.

SensitivityLevel

The sensitivity level of a command or state.

Enums
SENSITIVITY_LEVEL_UNSPECIFIED The default value. This value is used if the sensitivity level is omitted.
SENSITIVITY_LEVEL_L1 The sensitivity level is L1, which is the lowest sensitivity level.
SENSITIVITY_LEVEL_L2 The sensitivity level is L2, which is the second lowest sensitivity level.
SENSITIVITY_LEVEL_L3 The sensitivity level is L3, which is the third lowest sensitivity level.
SENSITIVITY_LEVEL_L4 The sensitivity level is L4, which is the highest sensitivity level.

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: ✅