MCP Tools Reference: firestore.googleapis.com

Tool: list_documents

List documents from a Firestore database.

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

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

Input Schema

The request for Firestore.ListDocuments.

ListDocumentsRequest

JSON representation 
{
  "parent": string,
  "collectionId": string,
  "recursive": boolean,
  "pageSize": integer,
  "pageToken": string,
  "orderBy": string,
  "mask": {
    object (DocumentMask)
  },
  "showMissing": boolean,

  // Union field consistency_selector can be only one of the following:
  "transaction": string,
  "readTime": string
  // End of list of possible types for union field consistency_selector.
}
Fields
parent

string

Required. The parent resource name. In the format: projects/{project_id}/databases/{database_id}/documents or projects/{project_id}/databases/{database_id}/documents/{document_path}.

For example: projects/my-project/databases/my-database/documents or projects/my-project/databases/my-database/documents/chatrooms/my-chatroom
collectionId

string

Optional. The collection ID, relative to parent, to list.

For example: chatrooms or messages.

This is optional, and when not provided, Firestore will list documents from all collections under the provided parent.
recursive

boolean

Optional. If the list should recursively include all documents nested under the parent at any level. If the request specifies a collection_id, then the list will include all nested documents in the collection under the parent.

This is optional, and when not provided, Firestore will only list documents nested immediately under the parent.

Requests with recursive may not specify show_missing.
pageSize

integer

Optional. The maximum number of documents to return in a single response.

Firestore may return fewer than this value.
pageToken

string

Optional. A page token, received from a previous ListDocuments response.

Provide this to retrieve the subsequent page. When paginating, all other parameters (with the exception of page_size) must match the values set in the request that generated the page token.
orderBy

string

Optional. The optional ordering of the documents to return.

For example: priority desc, __name__ desc.

This mirrors the ORDER BY used in Firestore queries but in a string representation. When absent, documents are ordered based on __name__ ASC.
mask

object (DocumentMask)

Optional. The fields to return. If not set, returns all fields.

If a document has a field that is not present in this mask, that field will not be returned in the response.
showMissing

boolean

If the list should show missing documents.

A document is missing if it does not exist, but there are sub-documents nested underneath it. When true, such missing documents will be returned with a key but will not have fields, create_time, or update_time set.

Requests with show_missing may not specify where or order_by.
Union field consistency_selector. The consistency mode for this transaction. If not set, defaults to strong consistency. consistency_selector can be only one of the following:
transaction

string (bytes format)

Perform the read as part of an already active transaction.

A base64-encoded string.
readTime

string (Timestamp format)

Perform the read at the provided time.

This must be a microsecond precision timestamp within the past one hour, or if Point-in-Time Recovery is enabled, can additionally be a whole minute timestamp within the past 7 days.

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

DocumentMask

JSON representation 
{
  "fieldPaths": [
    string
  ]
}
Fields
fieldPaths[]

string

The list of field paths in the mask. See Document.fields for a field path syntax reference.

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.

Output Schema

The response for Firestore.ListDocuments.

ListDocumentsResponse

JSON representation 
{
  "documents": [
    {
      object (Document)
    }
  ],
  "nextPageToken": string
}
Fields
documents[]

object (Document)

The Documents found.
nextPageToken

string

A token to retrieve the next page of documents.

If this field is omitted, there are no subsequent pages.

Document

JSON representation 
{
  "name": string,
  "fields": {
    string: {
      object (Value)
    },
    ...
  },
  "createTime": string,
  "updateTime": string
}
Fields
name

string

The resource name of the document, for example projects/{project_id}/databases/{database_id}/documents/{document_path}.
fields

map (key: string, value: object (Value))

The document's fields.

The map keys represent field names.

Field names matching the regular expression __.*__ are reserved. Reserved field names are forbidden except in certain documented contexts. The field names, represented as UTF-8, must not exceed 1,500 bytes and cannot be empty.

Field paths may be used in other contexts to refer to structured fields defined here. For map_value, the field path is represented by a dot-delimited (.) string of segments. Each segment is either a simple field name (defined below) or a quoted field name. For example, the structured field "foo" : { map_value: { "x&y" : { string_value: "hello" }}} would be represented by the field path foo.`x&y`.

A simple field name contains only characters a to z, A to Z, 0 to 9, or _, and must not start with 0 to 9. For example, foo_bar_17.

A quoted field name starts and ends with ` and may contain any character. Some characters, including `, must be escaped using a \. For example, `x&y` represents x&y and `bak\`tik` represents bak`tik.

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

string (Timestamp format)

Output only. The time at which the document was created.

This value increases monotonically when a document is deleted then recreated. It can also be compared to values from other documents and the read_time of a query.

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. The time at which the document was last changed.

This value is initially set to the create_time then increases monotonically with each change to the document. It can also be compared to values from other documents and the read_time of a query.

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

FieldsEntry

JSON representation 
{
  "key": string,
  "value": {
    object (Value)
  }
}
Fields
key

string
value

object (Value)

Value

JSON representation 
{

  // Union field value_type can be only one of the following:
  "nullValue": null,
  "booleanValue": boolean,
  "integerValue": string,
  "doubleValue": number,
  "timestampValue": string,
  "stringValue": string,
  "bytesValue": string,
  "referenceValue": string,
  "geoPointValue": {
    object (LatLng)
  },
  "arrayValue": {
    object (ArrayValue)
  },
  "mapValue": {
    object (MapValue)
  },
  "fieldReferenceValue": string,
  "variableReferenceValue": string,
  "functionValue": {
    object (Function)
  },
  "pipelineValue": {
    object (Pipeline)
  }
  // End of list of possible types for union field value_type.
}
Fields
Union field value_type. Must have a value set. value_type can be only one of the following:
nullValue

null

A null value.
booleanValue

boolean

A boolean value.
integerValue

string (int64 format)

An integer value.
doubleValue

number

A double value.
timestampValue

string (Timestamp format)

A timestamp value.

Precise only to microseconds. When stored, any additional precision is rounded down.

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

string

A string value.

In Standard edition databases:

  • The string, represented as UTF-8, must not exceed 1 MiB - 89 bytes.
  • Only the first 1,500 bytes of the UTF-8 representation are considered by queries.

In Enterprise edition databases, there is no limit on the size of the value. However, it is still subject to document and index entry size limits.
bytesValue

string (bytes format)

A bytes value.

In Standard edition databases:

  • The value must not exceed 1 MiB - 89 bytes.
  • Only the first 1,500 bytes are considered by queries.

In Enterprise edition databases, there is no limit on the size of the value. However, it is still subject to document and index entry size limits.

A base64-encoded string.
referenceValue

string

A reference to a document. For example: projects/{project_id}/databases/{database_id}/documents/{document_path}.
geoPointValue

object (LatLng)

A geo point value representing a point on the surface of Earth.
arrayValue

object (ArrayValue)

An array value.

In Standard edition databases, an array value cannot directly contain another array value, though it can contain a map which contains another array.

In Enterprise edition databases, an array value can contain another array value.
mapValue

object (MapValue)

A map value.
fieldReferenceValue

string

Value which references a field.

This is considered relative (vs absolute) since it only refers to a field and not a field within a particular document.

Requires:

  • Must follow [field reference][FieldReference.field_path] limitations.

  • Not allowed to be used when writing documents.
variableReferenceValue

string

Pointer to a variable defined elsewhere in a pipeline.

Unlike field_reference_value which references a field within a document, this refers to a variable, defined in a separate namespace than the fields of a document.
functionValue

object (Function)

A value that represents an unevaluated expression.

Requires:

  • Not allowed to be used when writing documents.
pipelineValue

object (Pipeline)

A value that represents an unevaluated pipeline.

Requires:

  • Not allowed to be used when writing documents.

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.

LatLng

JSON representation 
{
  "latitude": number,
  "longitude": number
}
Fields
latitude

number

The latitude in degrees. It must be in the range [-90.0, +90.0].
longitude

number

The longitude in degrees. It must be in the range [-180.0, +180.0].

ArrayValue

JSON representation 
{
  "values": [
    {
      object (Value)
    }
  ]
}
Fields
values[]

object (Value)

Values in the array.

MapValue

JSON representation 
{
  "fields": {
    string: {
      object (Value)
    },
    ...
  }
}
Fields
fields

map (key: string, value: object (Value))

The map's fields.

The map keys represent field names. Field names matching the regular expression __.*__ are reserved. Reserved field names are forbidden except in certain documented contexts. The map keys, represented as UTF-8, must not exceed 1,500 bytes and cannot be empty.

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

FieldsEntry

JSON representation 
{
  "key": string,
  "value": {
    object (Value)
  }
}
Fields
key

string
value

object (Value)

Function

JSON representation 
{
  "name": string,
  "args": [
    {
      object (Value)
    }
  ],
  "options": {
    string: {
      object (Value)
    },
    ...
  }
}
Fields
name

string

Required. The name of the function to evaluate.

Requires:

  • must be in snake case (lower case with underscore separator).
args[]

object (Value)

Optional. Ordered list of arguments the given function expects.
options

map (key: string, value: object (Value))

Optional. Optional named arguments that certain functions may support.

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

OptionsEntry

JSON representation 
{
  "key": string,
  "value": {
    object (Value)
  }
}
Fields
key

string
value

object (Value)

Pipeline

JSON representation 
{
  "stages": [
    {
      object (Stage)
    }
  ]
}
Fields
stages[]

object (Stage)

Required. Ordered list of stages to evaluate.

Stage

JSON representation 
{
  "name": string,
  "args": [
    {
      object (Value)
    }
  ],
  "options": {
    string: {
      object (Value)
    },
    ...
  }
}
Fields
name

string

Required. The name of the stage to evaluate.

Requires:

  • must be in snake case (lower case with underscore separator).
args[]

object (Value)

Optional. Ordered list of arguments the given stage expects.
options

map (key: string, value: object (Value))

Optional. Optional named arguments that certain functions may support.

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

OptionsEntry

JSON representation 
{
  "key": string,
  "value": {
    object (Value)
  }
}
Fields
key

string
value

object (Value)

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.

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