MCP Tools Reference: capacityplanner.googleapis.com

Tool: query_usage_histories

Returns daily historical usage time series for resources like Compute Engine (vCPUs, RAM, Local SSD, Persistent Disk, GPUs, and TPUs) and Cloud Storage bucket read throughput in a project, folder, or organization, at the regional or zonal level. Use this tool to analyze past consumption trends. Requires parent (for example, 'projects/{project}/locations/{location}', 'folders/{folder}/locations/{location}', or 'organizations/{organization}/locations/{location}') and cloudResourceType.

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

Curl Request 
curl --location 'https://capacityplanner.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "query_usage_histories",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Input Schema

The QueryUsageHistories request.

QueryUsageHistoriesRequest

JSON representation 
{
  "parent": string,
  "locationLevel": enum (LocationType),
  "isSpot": boolean,
  "machineFamily": string,
  "machineShape": {
    object (MachineShape)
  },
  "diskType": string,
  "confidentialMode": boolean,
  "gpuType": string,
  "tpuType": string,
  "gcsBucketTraffic": {
    object (GcsBucketTraffic)
  },
  "cloudResourceType": string,
  "usageAggregationMethod": enum (AggregationMethod),
  "startDate": {
    object (Date)
  },
  "endDate": {
    object (Date)
  }
}
Fields
parent

string

Required. The project, folder, or organization and location for the time series values to return. The format is:

projects/{project}/locations/{location} or
organizations/{organization}/locations/{location} or
folders/{folder}/locations/{location}
locationLevel

enum (LocationType)

Optional. The location level (regional or zonal) of the usage time series to return.
isSpot

boolean

Optional. Whether to return usage data for Spot (preemptible) resources.
machineFamily

string

Optional. The machine family for the UsageHistory values to return. Possible values include "n1", and "n2d". See https://cloud.google.com/compute/docs/machine-types for more examples. Empty machine_family will return results matching all machine families.
machineShape

object (MachineShape)

Optional. The machine shape for the UsageHistory values to return.
diskType

string

Optional. The disk_type for the UsageHistory values to return request with persistent-disk cloud_resource_type. Empty disk_type will return results matching all disk types.
confidentialMode

boolean

Optional. Whether the persistent disk is in confidential mode.
gpuType

string

Optional. The GPU type for the UsageHistory values to return. Sample values are "nvidia-tesla-t4", and "nvidia-tesla-a100". See https://cloud.google.com/compute/docs/gpus for a list. Empty gpu_type will return results matching all GPUs.
tpuType

string

Optional. The TPU type for the UsageHistory values to return. Empty tpu_type will return results matching all TPUs.
gcsBucketTraffic

object (GcsBucketTraffic)

Optional. Cloud Storage bucket traffic resource for the UsageHistory values to return.
cloudResourceType

string

Required. The resource for the UsageHistory values to return. Possible values include "gce-vcpus", "gce-ram", "gce-local-ssd", "gce-persistent-disk", "gce-gpu" and "gce-tpu" and "gcs-bucket-read-throughput".
usageAggregationMethod

enum (AggregationMethod)

Optional. The method that should be used to convert sampled usage data to daily usage values. AGGREGATION_METHOD_UNSPECIFIED will return results matching all the aggregation methods.
startDate

object (Date)

Optional. The start date of the usage history to return.
endDate

object (Date)

Optional. The end date of the usage history to return.

MachineShape

JSON representation 
{
  "machineFamily": string,
  "machineType": string,
  "machineShape": string,
  "cpuCores": number,
  "gpuType": string,
  "gpuComputeType": string,
  "gpuCores": string,
  "localSsdPartitions": string,
  "localSsdGb": number,
  "memoryGb": number,
  "localSsdInterface": string,
  "minCpuPlatform": string
}
Fields
machineFamily

string

Optional. The VM family.
machineType

string

Optional. The characteristics of the sampled VM expressed as a string.
machineShape

string

Optional. The customer visible string representing the type of VM.
cpuCores

number

Optional. Number of CPU cores per VM.
gpuType

string

Optional. The type of GPU with the VM.
gpuComputeType

string

Optional. The GPU name recognized by Compute Engine APIs.
gpuCores

string (int64 format)

Optional. The number of GPU cores per VM.
localSsdPartitions

string (int64 format)

Optional. The number of local SSD partitions per VM.
localSsdGb

number

Optional. Total amount of local SSD storage.
memoryGb

number

Optional. Total amount of memory with the VM.
localSsdInterface

string

Optional. The local SSD interface used such as nvme or scsi
minCpuPlatform

string

Optional. The minimum CPU platform used, such as icelake.

GcsBucketTraffic

JSON representation 
{
  "trafficPath": enum (TrafficPath),
  "bucketLocationType": enum (LocationType),
  "bucketLocation": string
}
Fields
trafficPath

enum (TrafficPath)

Optional. Path type for the Cloud Storage bucket traffic.
bucketLocationType

enum (LocationType)

Optional. Location type of the Cloud Storage bucket.
bucketLocation

string

Optional. Location of the Cloud Storage bucket e.g. us-central1 (single region), us (multi region) and eur4 - europe-north1 and europe-west4 (dual region).

Date

JSON representation 
{
  "year": integer,
  "month": integer,
  "day": integer
}
Fields
year

integer

Year of the date. Must be from 1 to 9999, or 0 to specify a date without a year.
month

integer

Month of a year. Must be from 1 to 12, or 0 to specify a year without a month and day.
day

integer

Day of a month. Must be from 1 to 31 and valid for the year and month, or 0 to specify a year by itself or a year and month where the day isn't significant.

LocationType

The type of location that the time series is summarizing.

Enums
LOCATION_TYPE_UNSPECIFIED No location type was specified.
REGIONAL Time series values represent usage aggregated at the region level.
ZONAL Time series values represent usage aggregated at the zone level.

TrafficPath

Path type for the Cloud Storage bucket traffic.

Enums
TRAFFIC_PATH_UNSPECIFIED Unspecified traffic path.
TRAFFIC_PATH_GOOGLE Traffic path through Google's network.
TRAFFIC_PATH_INTERNET Traffic path through the internet.

LocationType

Location type/level of the Cloud Storage bucket.

Enums
LOCATION_TYPE_UNSPECIFIED Unspecified location type.
LOCATION_TYPE_SINGLE_REGION Single region location type.
LOCATION_TYPE_DUAL_REGION Dual region location type.
LOCATION_TYPE_MULTI_REGION Multi region location type.

AggregationMethod

Methods for converting sampled data to time series values.

Enums
AGGREGATION_METHOD_UNSPECIFIED No aggregation method is specified.
MEDIAN Deprecated: Use P50 instead.
PEAK Deprecated: Use P99 instead.
P50 Time series values represent the 50th(median) percentile of the sampled values.
P75 Time series values represent the 75th percentile of the sampled values.
P99 Time series values represent the 99th percentile of the sampled values.
P100 Time series values represent the max of the sampled values.

Output Schema

The QueryUsageHistories response.

QueryUsageHistoriesResponse

JSON representation 
{
  "usageHistories": [
    {
      object (UsageHistory)
    }
  ]
}
Fields
usageHistories[]

object (UsageHistory)

The usage histories that match the request.

UsageHistory

JSON representation 
{
  "timeSeries": {
    object (TimeSeries)
  },
  "aggregationMethod": enum (AggregationMethod)
}
Fields
timeSeries

object (TimeSeries)

The collection of data points that represent the historical values.
aggregationMethod

enum (AggregationMethod)

Method used to convert sampled usage data to time series values.

TimeSeries

JSON representation 
{
  "locationType": enum (LocationType),
  "location": string,
  "isSpot": boolean,
  "machineFamily": string,
  "diskType": string,
  "confidentialMode": boolean,
  "gpuType": string,
  "tpuType": string,
  "machineShape": {
    object (MachineShape)
  },
  "gcsBucketTraffic": {
    object (GcsBucketTraffic)
  },
  "cloudResourceType": string,
  "points": [
    {
      object (Point)
    }
  ],
  "unit": string
}
Fields
locationType

enum (LocationType)

Required. The type of location that the time series is summarizing.
location

string

Optional. The location of the usage data in time series.
isSpot

boolean

Optional. Whether the time series represents usage of Spot (preemptible) resources.
machineFamily

string

The machine family for the time series values to return. Possible values include "n1" and "n2d".
diskType

string

The disk type for the time series values to return.
confidentialMode

boolean

Optional. The confidential mode for disk.
gpuType

string

The GPU type of the time series.
tpuType

string

The TPU type of the time series.
machineShape

object (MachineShape)

The machine shape of the time series.
gcsBucketTraffic

object (GcsBucketTraffic)

Output only. The Cloud Storage bucket traffic resource for usage time series.
cloudResourceType

string

The resource for the time series values to return. Possible values include "gce-vcpus", "gce-ram", "gce-local-ssd", "gce-persistent-disk", "gce-gpu", "gce-tpu" and "gce-vm".
points[]

object (Point)

The data points of this time series. When listing time series, points are returned in chronological order.
unit

string

The units in which the values are reported.

MachineShape

JSON representation 
{
  "machineFamily": string,
  "machineType": string,
  "machineShape": string,
  "cpuCores": number,
  "gpuType": string,
  "gpuComputeType": string,
  "gpuCores": string,
  "localSsdPartitions": string,
  "localSsdGb": number,
  "memoryGb": number,
  "localSsdInterface": string,
  "minCpuPlatform": string
}
Fields
machineFamily

string

Optional. The VM family.
machineType

string

Optional. The characteristics of the sampled VM expressed as a string.
machineShape

string

Optional. The customer visible string representing the type of VM.
cpuCores

number

Optional. Number of CPU cores per VM.
gpuType

string

Optional. The type of GPU with the VM.
gpuComputeType

string

Optional. The GPU name recognized by Compute Engine APIs.
gpuCores

string (int64 format)

Optional. The number of GPU cores per VM.
localSsdPartitions

string (int64 format)

Optional. The number of local SSD partitions per VM.
localSsdGb

number

Optional. Total amount of local SSD storage.
memoryGb

number

Optional. Total amount of memory with the VM.
localSsdInterface

string

Optional. The local SSD interface used such as nvme or scsi
minCpuPlatform

string

Optional. The minimum CPU platform used, such as icelake.

GcsBucketTraffic

JSON representation 
{
  "trafficPath": enum (TrafficPath),
  "bucketLocationType": enum (LocationType),
  "bucketLocation": string
}
Fields
trafficPath

enum (TrafficPath)

Optional. Path type for the Cloud Storage bucket traffic.
bucketLocationType

enum (LocationType)

Optional. Location type of the Cloud Storage bucket.
bucketLocation

string

Optional. Location of the Cloud Storage bucket e.g. us-central1 (single region), us (multi region) and eur4 - europe-north1 and europe-west4 (dual region).

Point

JSON representation 
{
  "eventTime": string,
  "value": number
}
Fields
eventTime

string (Timestamp format)

The time which the data point applies.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
value

number

The value of the data point.

Timestamp

JSON representation 
{
  "seconds": string,
  "nanos": integer
}
Fields
seconds

string (int64 format)

Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be between -62135596800 and 253402300799 inclusive (which corresponds to 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z).
nanos

integer

Non-negative fractions of a second at nanosecond resolution. This field is the nanosecond portion of the duration, not an alternative to seconds. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be between 0 and 999,999,999 inclusive.

LocationType

The type of location that the time series is summarizing.

Enums
LOCATION_TYPE_UNSPECIFIED No location type was specified.
REGIONAL Time series values represent usage aggregated at the region level.
ZONAL Time series values represent usage aggregated at the zone level.

TrafficPath

Path type for the Cloud Storage bucket traffic.

Enums
TRAFFIC_PATH_UNSPECIFIED Unspecified traffic path.
TRAFFIC_PATH_GOOGLE Traffic path through Google's network.
TRAFFIC_PATH_INTERNET Traffic path through the internet.

LocationType

Location type/level of the Cloud Storage bucket.

Enums
LOCATION_TYPE_UNSPECIFIED Unspecified location type.
LOCATION_TYPE_SINGLE_REGION Single region location type.
LOCATION_TYPE_DUAL_REGION Dual region location type.
LOCATION_TYPE_MULTI_REGION Multi region location type.

AggregationMethod

Methods for converting sampled data to time series values.

Enums
AGGREGATION_METHOD_UNSPECIFIED No aggregation method is specified.
MEDIAN Deprecated: Use P50 instead.
PEAK Deprecated: Use P99 instead.
P50 Time series values represent the 50th(median) percentile of the sampled values.
P75 Time series values represent the 75th percentile of the sampled values.
P99 Time series values represent the 99th percentile of the sampled values.
P100 Time series values represent the max of the sampled values.

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