REST Resource: projects.locations.apps.tools

Resource: Tool

A tool represents an action that the CES agent can take to achieve certain goals.

JSON representation 
{
  "name": string,
  "displayName": string,
  "executionType": enum (ExecutionType),
  "createTime": string,
  "updateTime": string,
  "etag": string,
  "generatedSummary": string,

  // Union field tool_type can be only one of the following:
  "clientFunction": {
    object (ClientFunction)
  },
  "openApiTool": {
    object (OpenApiTool)
  },
  "googleSearchTool": {
    object (GoogleSearchTool)
  },
  "connectorTool": {
    object (ConnectorTool)
  },
  "dataStoreTool": {
    object (DataStoreTool)
  },
  "pythonFunction": {
    object (PythonFunction)
  },
  "mcpTool": {
    object (McpTool)
  },
  "systemTool": {
    object (SystemTool)
  }
  // End of list of possible types for union field tool_type.
}
Fields
name

string

Identifier. The unique identifier of the tool. Format: - projects/{project}/locations/{location}/apps/{app}/tools/{tool} for

projects/{project}/locations/{location}/apps/{app}/toolsets/{toolset}/tools/{tool} for tools retrieved from a toolset. These tools are dynamic and output-only, they cannot be referenced directly where a tool is expected.
displayName

string

Output only. The display name of the tool, derived based on the tool's type. For example, display name of a [ClientFunction][Tool.ClientFunction] is derived from its name property.
executionType

enum (ExecutionType)

Optional. The execution type of the tool.
createTime

string (Timestamp format)

Output only. Timestamp when the tool was created.

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

string (Timestamp format)

Output only. Timestamp when the tool was last updated.

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

string

Etag used to ensure the object hasn't changed during a read-modify-write operation. If the etag is empty, the update will overwrite any concurrent changes.
generatedSummary

string

Output only. If the tool is generated by the LLM assistant, this field contains a descriptive summary of the generation.
Union field tool_type. The type of the tool. tool_type can be only one of the following:
clientFunction

object (ClientFunction)

Optional. The client function.
openApiTool

object (OpenApiTool)

Optional. The open API tool.
googleSearchTool

object (GoogleSearchTool)

Optional. The google search tool.
connectorTool

object (ConnectorTool)

Optional. The Integration Connector tool.
dataStoreTool

object (DataStoreTool)

Optional. The data store tool.
pythonFunction

object (PythonFunction)

Optional. The python function tool.
mcpTool

object (McpTool)

Optional. The MCP tool. An MCP tool cannot be created or updated directly and is managed by the MCP toolset.
systemTool

object (SystemTool)

Optional. The system tool.

ClientFunction

Represents a client-side function that the agent can invoke. When the tool is chosen by the agent, control is handed off to the client. The client is responsible for executing the function and returning the result as a ToolResponse to continue the interaction with the agent.

JSON representation 
{
  "name": string,
  "description": string,
  "parameters": {
    object (Schema)
  },
  "response": {
    object (Schema)
  }
}
Fields
name

string

Required. The function name.
description

string

Optional. The function description.
parameters

object (Schema)

Optional. The schema of the function parameters.
response

object (Schema)

Optional. The schema of the function response.

OpenApiTool

A remote API tool defined by an OpenAPI schema.

JSON representation 
{
  "openApiSchema": string,
  "name": string,
  "description": string,
  "apiAuthentication": {
    object (ApiAuthentication)
  },
  "tlsConfig": {
    object (TlsConfig)
  },
  "serviceDirectoryConfig": {
    object (ServiceDirectoryConfig)
  },
  "ignoreUnknownFields": boolean,
  "url": string
}
Fields
openApiSchema

string

Required. The OpenAPI schema in JSON or YAML format.
name

string

Optional. The name of the tool. If not provided, the name of the tool will be derived from the OpenAPI schema, from operation.operationId.
description

string

Optional. The description of the tool. If not provided, the description of the tool will be derived from the OpenAPI schema, from operation.description or operation.summary.
apiAuthentication

object (ApiAuthentication)

Optional. Authentication information required by the API.
tlsConfig

object (TlsConfig)

Optional. The TLS configuration. Includes the custom server certificates that the client will trust.
serviceDirectoryConfig

object (ServiceDirectoryConfig)

Optional. Service Directory configuration.
ignoreUnknownFields

boolean

Optional. If true, the agent will ignore unknown fields in the API response.
url

string

Optional. The server URL of the Open API schema. This field is only set in tools in the environment dependencies during the export process if the schema contains a server url. During the import process, if this url is present in the environment dependencies and the schema has the $env_var placeholder, it will replace the placeholder in the schema.

GoogleSearchTool

Represents a tool to perform Google web searches for grounding. See https://cloud.google.com/customer-engagement-ai/conversational-agents/ps/tool#google-search.

JSON representation 
{
  "name": string,
  "description": string,
  "contextUrls": [
    string
  ],
  "preferredDomains": [
    string
  ],
  "excludeDomains": [
    string
  ]
}
Fields
name

string

Required. The name of the tool.
description

string

Optional. Description of the tool's purpose.
contextUrls[]

string

Optional. Content will be fetched directly from these URLs for context and grounding. More details: https://cloud.google.com/vertex-ai/generative-ai/docs/url-context. Example: "https://example.com/path.html". A maximum of 20 URLs are allowed.
preferredDomains[]

string

Optional. Specifies domain names to guide the search. The model will be instructed to prioritize these domains when formulating queries for google search. This is a best-effort hint and these domains may or may not be exclusively reflected in the final search results. Example: "example.com", "another.site". A maximum of 20 domains can be specified.
excludeDomains[]

string

Optional. List of domains to be excluded from the search results. Example: "example.com". A maximum of 2000 domains can be excluded.

ConnectorTool

A ConnectorTool allows connections to different integrations. See: https://cloud.google.com/integration-connectors/docs/overview.

JSON representation 
{
  "connection": string,
  "action": {
    object (Action)
  },
  "authConfig": {
    object (EndUserAuthConfig)
  },
  "name": string,
  "description": string
}
Fields
connection

string

Required. The full resource name of the referenced Integration Connectors Connection. Format: projects/{project}/locations/{location}/connections/{connection}
action

object (Action)

Required. Action for the tool to use.
authConfig

object (EndUserAuthConfig)

Optional. Configures how authentication is handled in Integration Connectors. By default, an admin authentication is passed in the Integration Connectors API requests. You can override it with a different end-user authentication config. Note: The Connection must have authentication override enabled in order to specify an EUC configuration here - otherwise, the ConnectorTool creation will fail. See https://cloud.google.com/application-integration/docs/configure-connectors-task#configure-authentication-override for details.
name

string

Optional. The name of the tool that can be used by the Agent to decide whether to call this ConnectorTool.
description

string

Optional. The description of the tool that can be used by the Agent to decide whether to call this ConnectorTool.

DataStoreTool

Tool to retrieve from Vertex AI Search datastore or engine for grounding. Accepts either a datastore or an engine, but not both. See Vertex AI Search: https://cloud.google.com/generative-ai-app-builder/docs/enterprise-search-introduction.

JSON representation 
{
  "name": string,
  "description": string,
  "maxResults": integer,
  "boostSpecs": [
    {
      object (DataStoreTool.BoostSpecs)
    }
  ],
  "modalityConfigs": [
    {
      object (DataStoreTool.ModalityConfig)
    }
  ],
  "filterParameterBehavior": enum (DataStoreTool.FilterParameterBehavior),

  // Union field search_source can be only one of the following:
  "dataStoreSource": {
    object (DataStoreTool.DataStoreSource)
  },
  "engineSource": {
    object (DataStoreTool.EngineSource)
  }
  // End of list of possible types for union field search_source.
}
Fields
name

string

Required. The data store tool name.
description

string

Optional. The tool description.
maxResults

integer

Optional. Number of search results to return per query. The default value is 10. The maximum allowed value is 10.
boostSpecs[]

object (DataStoreTool.BoostSpecs)

Optional. Boost specification to boost certain documents.
modalityConfigs[]

object (DataStoreTool.ModalityConfig)

Optional. The modality configs for the data store.
filterParameterBehavior

enum (DataStoreTool.FilterParameterBehavior)

Optional. The filter parameter behavior.
Union field search_source. Defines the search source, either a single DataStore or an Engine. search_source can be only one of the following:
dataStoreSource

object (DataStoreTool.DataStoreSource)

Optional. Search within a single specific DataStore.
engineSource

object (DataStoreTool.EngineSource)

Optional. Search within an Engine (potentially across multiple DataStores).

DataStoreTool.DataStoreSource

Configuration for searching within a specific DataStore.

JSON representation 
{
  "filter": string,
  "dataStore": {
    object (DataStore)
  }
}
Fields
filter

string

Optional. Filter specification for the DataStore. See: https://cloud.google.com/generative-ai-app-builder/docs/filter-search-metadata
dataStore

object (DataStore)

Optional. The data store.

DataStore

A DataStore resource in Vertex AI Search.

JSON representation 
{
  "name": string,
  "type": enum (DataStore.DataStoreType),
  "documentProcessingMode": enum (DataStore.DocumentProcessingMode),
  "displayName": string,
  "createTime": string,
  "connectorConfig": {
    object (DataStore.ConnectorConfig)
  }
}
Fields
name

string

Required. Full resource name of the DataStore. Format: projects/{project}/locations/{location}/collections/{collection}/dataStores/{dataStore}
type

enum (DataStore.DataStoreType)

Output only. The type of the data store. This field is readonly and populated by the server.
documentProcessingMode

enum (DataStore.DocumentProcessingMode)

Output only. The document processing mode for the data store connection. Only set for PUBLIC_WEB and UNSTRUCTURED data stores.
displayName

string

Output only. The display name of the data store.
createTime

string (Timestamp format)

Output only. Timestamp when the data store was created.

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

object (DataStore.ConnectorConfig)

Output only. The connector config for the data store connection.

DataStore.DataStoreType

The type of the data store.

Enums
DATA_STORE_TYPE_UNSPECIFIED Not specified. This value indicates that the data store type is not specified, so it will not be used during search.
PUBLIC_WEB A data store that contains public web content.
UNSTRUCTURED A data store that contains unstructured private data.
FAQ A data store that contains structured data used as FAQ.
CONNECTOR A data store that is a connector to a first-party or a third-party service.

DataStore.DocumentProcessingMode

The document processing mode of the data store.

Enums
DOCUMENT_PROCESSING_MODE_UNSPECIFIED Not specified.
DOCUMENTS Documents are processed as documents.
CHUNKS Documents are converted to chunks.

DataStore.ConnectorConfig

The connector config for the data store connection.

JSON representation 
{
  "collection": string,
  "collectionDisplayName": string,
  "dataSource": string
}
Fields
collection

string

Resource name of the collection the data store belongs to.
collectionDisplayName

string

Display name of the collection the data store belongs to.
dataSource

string

The name of the data source. Example: salesforce, jira, confluence, bigquery.

DataStoreTool.EngineSource

Configuration for searching within an Engine, potentially targeting specific DataStores.

JSON representation 
{
  "engine": string,
  "dataStoreSources": [
    {
      object (DataStoreTool.DataStoreSource)
    }
  ],
  "filter": string
}
Fields
engine

string

Required. Full resource name of the Engine. Format: projects/{project}/locations/{location}/collections/{collection}/engines/{engine}
dataStoreSources[]

object (DataStoreTool.DataStoreSource)

Optional. Use to target specific DataStores within the Engine. If empty, the search applies to all DataStores associated with the Engine.
filter

string

Optional. A filter applied to the search across the Engine. Not relevant and not used if 'dataStoreSources' is provided. See: https://cloud.google.com/generative-ai-app-builder/docs/filter-search-metadata

DataStoreTool.BoostSpecs

Boost specifications to boost certain documents. For more information, please refer to https://cloud.google.com/generative-ai-app-builder/docs/boosting.

JSON representation 
{
  "dataStores": [
    string
  ],
  "spec": [
    {
      object (DataStoreTool.BoostSpec)
    }
  ]
}
Fields
dataStores[]

string

Required. The Data Store where the boosting configuration is applied. Full resource name of DataStore, such as projects/{project}/locations/{location}/collections/{collection}/dataStores/{dataStore}.
spec[]

object (DataStoreTool.BoostSpec)

Required. A list of boosting specifications.

DataStoreTool.BoostSpec

Boost specification to boost certain documents.

JSON representation 
{
  "conditionBoostSpecs": [
    {
      object (DataStoreTool.BoostSpec.ConditionBoostSpec)
    }
  ]
}
Fields
conditionBoostSpecs[]

object (DataStoreTool.BoostSpec.ConditionBoostSpec)

Required. A list of boosting specifications.

DataStoreTool.BoostSpec.ConditionBoostSpec

Boost specification for a condition.

JSON representation 
{
  "condition": string,
  "boost": number,
  "boostControlSpec": {
    object (DataStoreTool.BoostSpec.ConditionBoostSpec.BoostControlSpec)
  }
}
Fields
condition

string

Required. An expression which specifies a boost condition. The syntax is the same as filter expression syntax. Currently, the only supported condition is a list of BCP-47 lang codes. Example: To boost suggestions in languages en or fr: (lang_code: ANY("en", "fr"))
boost

number

Optional. Strength of the boost, which should be in [-1, 1]. Negative boost means demotion. Default is 0.0.

Setting to 1.0 gives the suggestions a big promotion. However, it does not necessarily mean that the top result will be a boosted suggestion.

Setting to -1.0 gives the suggestions a big demotion. However, other suggestions that are relevant might still be shown.

Setting to 0.0 means no boost applied. The boosting condition is ignored.
boostControlSpec

object (DataStoreTool.BoostSpec.ConditionBoostSpec.BoostControlSpec)

Optional. Complex specification for custom ranking based on customer defined attribute value.

DataStoreTool.BoostSpec.ConditionBoostSpec.BoostControlSpec

Specification for custom ranking based on customer specified attribute value. It provides more controls for customized ranking than the simple (condition, boost) combination above.

JSON representation 
{
  "fieldName": string,
  "attributeType": enum (DataStoreTool.BoostSpec.ConditionBoostSpec.BoostControlSpec.AttributeType),
  "interpolationType": enum (DataStoreTool.BoostSpec.ConditionBoostSpec.BoostControlSpec.InterpolationType),
  "controlPoints": [
    {
      object (DataStoreTool.BoostSpec.ConditionBoostSpec.BoostControlSpec.ControlPoint)
    }
  ]
}
Fields
fieldName

string

Optional. The name of the field whose value will be used to determine the boost amount.
attributeType

enum (DataStoreTool.BoostSpec.ConditionBoostSpec.BoostControlSpec.AttributeType)

Optional. The attribute type to be used to determine the boost amount. The attribute value can be derived from the field value of the specified fieldName. In the case of numerical it is straightforward i.e. attributeValue = numerical_field_value. In the case of freshness however, attributeValue = (time.now() - datetime_field_value).
interpolationType

enum (DataStoreTool.BoostSpec.ConditionBoostSpec.BoostControlSpec.InterpolationType)

Optional. The interpolation type to be applied to connect the control points listed below.
controlPoints[]

object (DataStoreTool.BoostSpec.ConditionBoostSpec.BoostControlSpec.ControlPoint)

Optional. The control points used to define the curve. The monotonic function (defined through the interpolationType above) passes through the control points listed here.

DataStoreTool.BoostSpec.ConditionBoostSpec.BoostControlSpec.AttributeType

The attribute(or function) for which the custom ranking is to be applied.

Enums
ATTRIBUTE_TYPE_UNSPECIFIED Unspecified AttributeType.
NUMERICAL The value of the numerical field will be used to dynamically update the boost amount. In this case, the attributeValue (the x value) of the control point will be the actual value of the numerical field for which the boostAmount is specified.
FRESHNESS For the freshness use case the attribute value will be the duration between the current time and the date in the datetime field specified. The value must be formatted as an XSD dayTimeDuration value (a restricted subset of an ISO 8601 duration value). The pattern for this is: [nD][T[nH][nM][nS]]. E.g. 5D, 3DT12H30M, T24H.

DataStoreTool.BoostSpec.ConditionBoostSpec.BoostControlSpec.InterpolationType

The interpolation type to be applied. Default will be linear (Piecewise Linear).

Enums
INTERPOLATION_TYPE_UNSPECIFIED Interpolation type is unspecified. In this case, it defaults to Linear.
LINEAR Piecewise linear interpolation will be applied.

DataStoreTool.BoostSpec.ConditionBoostSpec.BoostControlSpec.ControlPoint

The control points used to define the curve. The curve defined through these control points can only be monotonically increasing or decreasing(constant values are acceptable).

JSON representation 
{
  "attributeValue": string,
  "boostAmount": number
}
Fields
attributeValue

string

Optional. Can be one of: 1. The numerical field value. 2. The duration spec for freshness: The value must be formatted as an XSD dayTimeDuration value (a restricted subset of an ISO 8601 duration value). The pattern for this is: [nD][T[nH][nM][nS]].
boostAmount

number

Optional. The value between -1 to 1 by which to boost the score if the attributeValue evaluates to the value specified above.

DataStoreTool.ModalityConfig

If specified, will apply the given configuration for the specified modality.

JSON representation 
{
  "modalityType": enum (DataStoreTool.ModalityConfig.ModalityType),
  "rewriterConfig": {
    object (DataStoreTool.RewriterConfig)
  },
  "summarizationConfig": {
    object (DataStoreTool.SummarizationConfig)
  },
  "groundingConfig": {
    object (DataStoreTool.GroundingConfig)
  }
}
Fields
modalityType

enum (DataStoreTool.ModalityConfig.ModalityType)

Required. The modality type.
rewriterConfig

object (DataStoreTool.RewriterConfig)

Optional. The rewriter config.
summarizationConfig

object (DataStoreTool.SummarizationConfig)

Optional. The summarization config.
groundingConfig

object (DataStoreTool.GroundingConfig)

Optional. The grounding configuration.

DataStoreTool.ModalityConfig.ModalityType

The modality type.

Enums
MODALITY_TYPE_UNSPECIFIED Unspecified modality type.
TEXT Text modality.
AUDIO Audio modality.

DataStoreTool.RewriterConfig

Rewriter configuration.

JSON representation 
{
  "modelSettings": {
    object (ModelSettings)
  },
  "prompt": string,
  "disabled": boolean
}
Fields
modelSettings

object (ModelSettings)

Required. Configurations for the LLM model.
prompt

string

Optional. The prompt definition. If not set, default prompt will be used.
disabled

boolean

Optional. Whether the rewriter is disabled.

DataStoreTool.SummarizationConfig

Summarization configuration.

JSON representation 
{
  "modelSettings": {
    object (ModelSettings)
  },
  "prompt": string,
  "disabled": boolean
}
Fields
modelSettings

object (ModelSettings)

Optional. Configurations for the LLM model.
prompt

string

Optional. The prompt definition. If not set, default prompt will be used.
disabled

boolean

Optional. Whether summarization is disabled.

DataStoreTool.GroundingConfig

Grounding configuration.

JSON representation 
{
  "groundingLevel": number,
  "disabled": boolean
}
Fields
groundingLevel

number

Optional. The groundedness threshold of the answer based on the retrieved sources. The value has a configurable range of [1, 5]. The level is used to threshold the groundedness of the answer, meaning that all responses with a groundedness score below the threshold will fall back to returning relevant snippets only.

For example, a level of 3 means that the groundedness score must be 3 or higher for the response to be returned.
disabled

boolean

Optional. Whether grounding is disabled.

DataStoreTool.FilterParameterBehavior

Filter parameter behavior.

Enums
FILTER_PARAMETER_BEHAVIOR_UNSPECIFIED Default filter behavior. Include filter parameter for connector datastores. For the rest of the datastore types, the filter input parameter is omitted.
ALWAYS_INCLUDE Always include filter parameter for all datastore types.
NEVER_INCLUDE The filter parameter is never included in the list of tool parameters, regardless of the datastore type.

PythonFunction

A Python function tool.

JSON representation 
{
  "name": string,
  "pythonCode": string,
  "description": string
}
Fields
name

string

Optional. The name of the Python function to execute. Must match a Python function name defined in the python code. Case sensitive. If the name is not provided, the first function defined in the python code will be used.
pythonCode

string

Optional. The Python code to execute for the tool.
description

string

Output only. The description of the Python function, parsed from the python code's docstring.

McpTool

An MCP tool. See https://modelcontextprotocol.io/specification/2025-06-18/server/tools for more details.

JSON representation 
{
  "name": string,
  "description": string,
  "inputSchema": {
    object (Schema)
  },
  "outputSchema": {
    object (Schema)
  },
  "serverAddress": string,
  "apiAuthentication": {
    object (ApiAuthentication)
  },
  "tlsConfig": {
    object (TlsConfig)
  },
  "serviceDirectoryConfig": {
    object (ServiceDirectoryConfig)
  }
}
Fields
name

string

Required. The name of the MCP tool.
description

string

Optional. The description of the MCP tool.
inputSchema

object (Schema)

Optional. The schema of the input arguments of the MCP tool.
outputSchema

object (Schema)

Optional. The schema of the output arguments of the MCP tool.
serverAddress

string

Required. The server address of the MCP server, e.g., "https://example.com/mcp/". If the server is built with the MCP SDK, the url should be suffixed with "/mcp/". Only Streamable HTTP transport based servers are supported. This is the same as the serverAddress in the McpToolset. See https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http for more details.
apiAuthentication

object (ApiAuthentication)

Optional. Authentication information required to execute the tool against the MCP server.
tlsConfig

object (TlsConfig)

Optional. The TLS configuration. Includes the custom server certificates that the client should trust.
serviceDirectoryConfig

object (ServiceDirectoryConfig)

Optional. Service Directory configuration for VPC-SC, used to resolve service names within a perimeter.

SystemTool

Pre-defined system tool.

JSON representation 
{
  "name": string,
  "description": string
}
Fields
name

string

Required. The name of the system tool.
description

string

Output only. The description of the system tool.

Methods

create

 Creates a new tool in the given app.

delete

 Deletes the specified tool.

get

 Gets details of the specified tool.

list

 Lists tools in the given app.

patch

 Updates the specified tool.