googleapis--mcp-toolbox/docs/en/integrations/cloud-storage/tools/cloud-storage-download-object.md

title, type, weight, description

title	type	weight	description
cloud-storage-download-object	docs	5	A "cloud-storage-download-object" tool downloads a Cloud Storage object to an absolute path on the Toolbox server filesystem.

About

A cloud-storage-download-object tool streams a Cloud Storage object to a local file on the Toolbox server. Unlike cloud-storage-read-object, it does not return the object bytes to the LLM and does not require UTF-8 text content, so it can be used for binary objects or large files.

The destination path is interpreted on the server where Toolbox is running. By default, destination must be an absolute path and paths containing .. are rejected. When destination_dir is configured on the tool, destination remains visible to the LLM but must be a relative path under that configured directory. Absolute paths and paths that escape destination_dir are rejected.

Compatible Sources

{{< compatible-sources >}}

Requirements

The Cloud Storage credentials must be able to read the object. The Toolbox server process must also be able to create or overwrite the destination file. When overwrite is false, the tool returns an agent-fixable error if the destination already exists.

Parameters

parameter	type	required	description
bucket	string	true	Name of the Cloud Storage bucket containing the object.
object	string	true	Full object name (path) within the bucket, e.g. path/to/file.txt.
destination	string	true	Absolute local filesystem path where the object will be written. Relative paths and paths containing .. are rejected.
overwrite	boolean	false	If true, overwrite the destination when it already exists. If false (default), return an error when it exists.

If bucket is configured on the tool, it is removed from the parameter list. If destination_dir is configured on the tool, destination stays in the parameter list but changes to a relative path under destination_dir. If overwrite is configured on the tool, it is removed from the parameter list.

Example

kind: tool
name: download_object
type: cloud-storage-download-object
source: my-gcs-source
description: Use this tool to download a Cloud Storage object to the server filesystem.

kind: tool
name: download_reports
type: cloud-storage-download-object
source: my-gcs-source
description: Use this tool to download report objects into the reports directory.
bucket: analytics-exports
destination_dir: /var/toolbox/downloads/reports
overwrite: false

Output Format

The tool returns a JSON object with:

field	type	description
destination	string	Local path where the object was written.
bytes	integer	Number of bytes written.
contentType	string	Content type recorded on the Cloud Storage object.

Reference

field	type	required	description
type	string	true	Must be "cloud-storage-download-object".
source	string	true	Name of the Cloud Storage source to download objects from.
description	string	true	Description of the tool that is passed to the LLM.
bucket	string	false	Cloud Storage bucket to use for every invocation. When set, bucket is hidden from the tool parameters.
destination_dir	string	false	Absolute local directory to contain downloaded files. When set, destination is a relative path under this directory.
overwrite	boolean	false	Whether to overwrite existing destination files for every invocation. When set, overwrite is hidden from the tool parameters.