MCP Tools Reference: recommender.googleapis.com

Tool: list_insights

Lists insights for a given cloud resource.

The following sample demonstrate how to use curl to invoke the list_insights MCP tool.

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

Input Schema

Request for the ListInsights method.

ListInsightsRequest

JSON representation 
{
  "parent": string,
  "pageSize": integer,
  "pageToken": string,
  "filter": string
}
Fields
parent

string

Required. The container resource on which to execute the request. Acceptable formats:

  • projects/[PROJECT_NUMBER]/locations/[LOCATION]/insightTypes/[INSIGHT_TYPE_ID]

  • projects/[PROJECT_ID]/locations/[LOCATION]/insightTypes/[INSIGHT_TYPE_ID]

  • billingAccounts/[BILLING_ACCOUNT_ID]/locations/[LOCATION]/insightTypes/[INSIGHT_TYPE_ID]

  • folders/[FOLDER_ID]/locations/[LOCATION]/insightTypes/[INSIGHT_TYPE_ID]

  • organizations/[ORGANIZATION_ID]/locations/[LOCATION]/insightTypes/[INSIGHT_TYPE_ID]

LOCATION here refers to GCP Locations: https://cloud.google.com/about/locations/ INSIGHT_TYPE_ID refers to supported insight types: https://cloud.google.com/recommender/docs/insights/insight-types.
pageSize

integer

Optional. The maximum number of results to return from this request. Non-positive values are ignored. If not specified, the server will determine the number of results to return.
pageToken

string

Optional. If present, retrieves the next batch of results from the preceding call to this method. page_token must be the value of next_page_token from the previous response. The values of other method parameters must be identical to those in the previous call.
filter

string

Optional. Filter expression to restrict the insights returned. Supported filter fields:

  • stateInfo.state

  • insightSubtype

  • severity

  • targetResources

Examples:

  • stateInfo.state = ACTIVE OR stateInfo.state = DISMISSED

  • insightSubtype = PERMISSIONS_USAGE

  • severity = CRITICAL OR severity = HIGH

  • targetResources : //compute.googleapis.com/projects/1234/zones/us-central1-a/instances/instance-1

  • stateInfo.state = ACTIVE AND (severity = CRITICAL OR severity = HIGH)

The max allowed filter length is 500 characters.

(These expressions are based on the filter language described at https://google.aip.dev/160)

Output Schema

Response to the ListInsights method.

ListInsightsResponse

JSON representation 
{
  "insights": [
    {
      object (Insight)
    }
  ],
  "nextPageToken": string
}
Fields
insights[]

object (Insight)

The set of insights for the parent resource.
nextPageToken

string

A token that can be used to request the next page of results. This field is empty if there are no additional results.

Insight

JSON representation 
{
  "name": string,
  "description": string,
  "targetResources": [
    string
  ],
  "insightSubtype": string,
  "content": {
    object
  },
  "lastRefreshTime": string,
  "observationPeriod": string,
  "stateInfo": {
    object (InsightStateInfo)
  },
  "category": enum (Category),
  "severity": enum (Severity),
  "etag": string,
  "associatedRecommendations": [
    {
      object (RecommendationReference)
    }
  ]
}
Fields
name

string

Identifier. Name of the insight.
description

string

Free-form human readable summary in English. The maximum length is 500 characters.
targetResources[]

string

Fully qualified resource names that this insight is targeting.
insightSubtype

string

Insight subtype. Insight content schema will be stable for a given subtype.
content

object (Struct format)

A struct of custom fields to explain the insight. Example: "grantedPermissionsCount": "1000"
lastRefreshTime

string (Timestamp format)

Timestamp of the latest data used to generate the insight.

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".
observationPeriod

string (Duration format)

Observation period that led to the insight. The source data used to generate the insight ends at last_refresh_time and begins at (last_refresh_time - observation_period).

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
stateInfo

object (InsightStateInfo)

Information state and metadata.
category

enum (Category)

Category being targeted by the insight.
severity

enum (Severity)

Insight's severity.
etag

string

Fingerprint of the Insight. Provides optimistic locking when updating states.
associatedRecommendations[]

object (RecommendationReference)

Recommendations derived from this insight.

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.

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.

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.

InsightStateInfo

JSON representation 
{
  "state": enum (State),
  "stateMetadata": {
    string: string,
    ...
  }
}
Fields
state

enum (State)

Insight state.
stateMetadata

map (key: string, value: string)

A map of metadata for the state, provided by user or automations systems.

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

StateMetadataEntry

JSON representation 
{
  "key": string,
  "value": string
}
Fields
key

string
value

string

RecommendationReference

JSON representation 
{
  "recommendation": string
}
Fields
recommendation

string

Recommendation resource name, e.g. projects/[PROJECT_NUMBER]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]/recommendations/[RECOMMENDATION_ID]

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.

State

Represents insight state.

Enums
STATE_UNSPECIFIED Unspecified state.
ACTIVE Insight is active. Content for ACTIVE insights can be updated by Google. ACTIVE insights can be marked DISMISSED OR ACCEPTED.
ACCEPTED Some action has been taken based on this insight. Insights become accepted when a recommendation derived from the insight has been marked CLAIMED, SUCCEEDED, or FAILED. ACTIVE insights can also be marked ACCEPTED explicitly. Content for ACCEPTED insights is immutable. ACCEPTED insights can only be marked ACCEPTED (which may update state metadata).
DISMISSED Insight is dismissed. Content for DISMISSED insights can be updated by Google. DISMISSED insights can be marked as ACTIVE.

Category

Insight category.

Enums
CATEGORY_UNSPECIFIED Unspecified category.
COST The insight is related to cost.
SECURITY The insight is related to security.
PERFORMANCE The insight is related to performance.
MANAGEABILITY This insight is related to manageability.
SUSTAINABILITY The insight is related to sustainability.
RELIABILITY This insight is related to reliability.

Severity

Insight severity levels.

Enums
SEVERITY_UNSPECIFIED Insight has unspecified severity.
LOW Insight has low severity.
MEDIUM Insight has medium severity.
HIGH Insight has high severity.
CRITICAL Insight has critical severity.

Tool Annotations

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