docs/en/integrations/cloud-storage/tools/cloud-storage-read-object.md
A cloud-storage-read-object tool fetches the bytes of a single
Cloud Storage object and returns them as plain UTF-8 text.
Only text objects are supported today: if the object bytes (or the requested range) are not valid UTF-8 the tool returns an agent-fixable error. This is because the MCP tool-result channel currently only carries text; binary payloads will be supported once MCP can carry embedded resources.
Reads are capped at 8 MiB per call to protect the server's memory and keep
LLM contexts manageable; objects or ranges larger than that are rejected with
an agent-fixable error. Use the optional range parameter to read a slice of
a larger object.
This tool is intended for small-to-medium textual content an LLM can process
directly. For bulk downloads of large files to the local filesystem, use
cloud-storage-download-object.
You can set bucket in the tool configuration. When set, bucket is removed
from the runtime parameter schema and the configured bucket is always used. A
configured bucket must be a non-empty string.
{{< compatible-sources >}}
| 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. |
| range | string | false | Optional HTTP byte range, e.g. bytes=0-999 (first 1000 bytes), bytes=-500 (last 500 bytes), or bytes=500- (from byte 500 to end). Empty reads the full object. |
kind: tool
name: read_object
type: cloud-storage-read-object
source: my-gcs-source
description: Use this tool to read the content of a Cloud Storage object.
kind: tool
name: read_app_object
type: cloud-storage-read-object
source: my-gcs-source
description: Use this tool to read text objects from the application bucket.
bucket: my-app-bucket
| field | type | required | description |
|---|---|---|---|
| type | string | true | Must be "cloud-storage-read-object". |
| source | string | true | Name of the Cloud Storage source to read the object from. |
| description | string | true | Description of the tool that is passed to the LLM. |
| bucket | string | false | Bucket to always read from. When set, the runtime bucket parameter is hidden. Must not be empty. |