grr

Overview Schema Source Related Servers Discussions Admin

drive.files.list

List and search Google Drive files using query filters, sorting, pagination, and shared-drive options; exclude trashed items or retrieve file metadata as JSON.

Instructions

Lists the user's files. For more information, see Search for files and folders. This method accepts the q parameter, which is a search query combining one or more search terms. This method returns all files by default, including trashed files. If you don't want trashed files to appear in the list, use the trashed=false query parameter to remove trashed files from the results [HTTP GET]. Returns the requested resource as JSON — request bodies are built from the typed parameters (typed flags win over the params map), or read whole from body_file Siblings over the same resource: copy, create, delete, download, emptyTrash, export, generateCseToken, generateIds, get, listLabels, modifyLabels, update, watch.

Input Schema

Name	Required	Description	Default
`q`	No	[query parameter] A query for filtering the file results. For supported syntax, see [Search for files and folders](/workspace/drive/api/guides/search-files).
`query`	No	Extra KEY=VALUE query pairs for endpoints whose parameters Discovery does not describe.
`corpus`	No	[query parameter] Deprecated: The source of files to list. Use `corpora` instead. Values: `domain` = Files shared to the user's domain.; `user` = Files owned by or shared to the user..
`params`	No	Parameter map merged into the request; typed parameters win.
`spaces`	No	[query parameter] A comma-separated list of spaces to query within the corpora. Supported values are `drive` and `appDataFolder`. For more information, see [File organization](ht	drive
`corpora`	No	[query parameter] Specifies a collection of items (files or documents) to which the query applies. Supported items include: * `user` * `domain` * `drive` * `allDrives` Prefer `us
`driveId`	No	[query parameter] ID of the shared drive to search.
`dry_run`	No	Return the request that would be sent, without sending it.
`orderBy`	No	[query parameter] A comma-separated list of sort keys. Valid keys are: * `createdTime`: When the file was created. Avoid using this key for queries on large item collections as i
`pageSize`	No	[query parameter] The maximum number of files to return. The service may return fewer than this value. If unspecified, at most 100 files will be returned for shared drives, and t	100
`body_file`	No	Read the request body from this file ('-' for stdin) instead of building one from the parameters.
`pageToken`	No	[query parameter] The token for continuing a previous list request on the next page. This should be set to the value of `nextPageToken` from the previous response.
`teamDriveId`	No	[query parameter] Deprecated: Use `driveId` instead.
`includeLabels`	No	[query parameter] A comma-separated list of IDs of labels to include in the `labelInfo` part of the response.
`supportsAllDrives`	No	[query parameter] Whether the requesting application supports both My Drives and shared drives.	false
`supportsTeamDrives`	No	[query parameter] Deprecated: Use `supportsAllDrives` instead.	false
`includeTeamDriveItems`	No	[query parameter] Deprecated: Use `includeItemsFromAllDrives` instead.	false
`includeItemsFromAllDrives`	No	[query parameter] Whether both My Drive and shared drive items should be included in results.	false
`includePermissionsForView`	No	[query parameter] Specifies which additional view's permissions to include in the response. Only `published` is supported.

Output Schema

Name	Required	Description	Default
`kind`	No
`files`	No
`nextPageToken`	No
`incompleteSearch`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed25 schema fields changedOct 26, 2026

changedInput schema / properties / corpora / description

Previous value: -"Specifies a collection of items (files or documents) to which the query applies. Supported items include: * `user` * `domain` * `drive` * `allDrives` Prefer `us"New value: +"[query parameter] Specifies a collection of items (files or documents) to which the query applies. Supported items include: * `user` * `domain` * `drive` * `allDrives` Prefer `us"

changedInput schema / properties / corpus / description

Previous value: -"Deprecated: The source of files to list. Use `corpora` instead."New value: +"[query parameter] Deprecated: The source of files to list. Use `corpora` instead. Values: `domain` = Files shared to the user's domain.; `user` = Files owned by or shared to the user.."

changedInput schema / properties / driveId / description

Previous value: -"ID of the shared drive to search."New value: +"[query parameter] ID of the shared drive to search."

addedInput schema / properties / includeItemsFromAllDrives / default
```
Added value: +"false"
```

changedInput schema / properties / includeItemsFromAllDrives / description

Previous value: -"Whether both My Drive and shared drive items should be included in results."New value: +"[query parameter] Whether both My Drive and shared drive items should be included in results."

changedInput schema / properties / includeLabels / description

Previous value: -"A comma-separated list of IDs of labels to include in the `labelInfo` part of the response."New value: +"[query parameter] A comma-separated list of IDs of labels to include in the `labelInfo` part of the response."

changedInput schema / properties / includePermissionsForView / description

Previous value: -"Specifies which additional view's permissions to include in the response. Only `published` is supported."New value: +"[query parameter] Specifies which additional view's permissions to include in the response. Only `published` is supported."

addedInput schema / properties / includeTeamDriveItems / default
```
Added value: +"false"
```

changedInput schema / properties / includeTeamDriveItems / description

Previous value: -"Deprecated: Use `includeItemsFromAllDrives` instead."New value: +"[query parameter] Deprecated: Use `includeItemsFromAllDrives` instead."

changedInput schema / properties / orderBy / description

Previous value: -"A comma-separated list of sort keys. Valid keys are: * `createdTime`: When the file was created. Avoid using this key for queries on large item collections as i"New value: +"[query parameter] A comma-separated list of sort keys. Valid keys are: * `createdTime`: When the file was created. Avoid using this key for queries on large item collections as i"

addedInput schema / properties / pageSize / default
```
Added value: +"100"
```

changedInput schema / properties / pageSize / description

Previous value: -"The maximum number of files to return. The service may return fewer than this value. If unspecified, at most 100 files will be returned for shared drives, and t"New value: +"[query parameter] The maximum number of files to return. The service may return fewer than this value. If unspecified, at most 100 files will be returned for shared drives, and t"

addedInput schema / properties / pageSize / format
```
Added value: +"int32"
```
addedInput schema / properties / pageSize / maximum
```
Added value: +1000
```
addedInput schema / properties / pageSize / minimum
```
Added value: +1
```

changedInput schema / properties / pageToken / description

Previous value: -"The token for continuing a previous list request on the next page. This should be set to the value of `nextPageToken` from the previous response."New value: +"[query parameter] The token for continuing a previous list request on the next page. This should be set to the value of `nextPageToken` from the previous response."

changedInput schema / properties / q / description

Previous value: -"A query for filtering the file results. For supported syntax, see [Search for files and folders](/workspace/drive/api/guides/search-files)."New value: +"[query parameter] A query for filtering the file results. For supported syntax, see [Search for files and folders](/workspace/drive/api/guides/search-files)."

addedInput schema / properties / spaces / default
```
Added value: +"drive"
```

changedInput schema / properties / spaces / description

Previous value: -"A comma-separated list of spaces to query within the corpora. Supported values are `drive` and `appDataFolder`. For more information, see [File organization](ht"New value: +"[query parameter] A comma-separated list of spaces to query within the corpora. Supported values are `drive` and `appDataFolder`. For more information, see [File organization](ht"

addedInput schema / properties / supportsAllDrives / default
```
Added value: +"false"
```

changedInput schema / properties / supportsAllDrives / description

Previous value: -"Whether the requesting application supports both My Drives and shared drives."New value: +"[query parameter] Whether the requesting application supports both My Drives and shared drives."

addedInput schema / properties / supportsTeamDrives / default
```
Added value: +"false"
```

changedInput schema / properties / supportsTeamDrives / description

Previous value: -"Deprecated: Use `supportsAllDrives` instead."New value: +"[query parameter] Deprecated: Use `supportsAllDrives` instead."

changedInput schema / properties / teamDriveId / description

Previous value: -"Deprecated: Use `driveId` instead."New value: +"[query parameter] Deprecated: Use `driveId` instead."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "files": {
+      "items": {
+        "properties": {
+          "appProperties": {
+            "type": "object"
+          },
+          "capabilities": {
+            "properties": {
+              "canAcceptOwnership": {
+                "type": "boolean"
+              },
+              "canAccessViaGenAi": {
+                "type": "boolean"
+              },
+              "canAddChildren": {
+                "type": "boolean"
+              },
+              "canAddFolderFromAnotherDrive": {
+                "type": "boolean"
+              },
+              "canAddMyDriveParent": {
+                "type": "boolean"
+              },
+              "canChangeCopyRequiresWriterPermission": {
+                "type": "boolean"
+              },
+              "canChangeItemDownloadRestriction": {
+                "type": "boolean"
+              },
+              "canChangeSecurityUpdateEnabled": {
+                "type": "boolean"
+              },
+              "canChangeViewersCanCopyContent": {
+                "type": "boolean"
+              },
+              "canComment": {
+                "type": "boolean"
+              },
+              "canCopy": {
+                "type": "boolean"
+              },
+              "canDelete": {
+                "type": "boolean"
+              },
+              "canDeleteChildren": {
+                "type": "boolean"
+              },
+              "canDisableInheritedPermissions": {
+                "type": "boolean"
+              },
+              "canDownload": {
+                "type": "boolean"
+              },
+              "canEdit": {
+                "type": "boolean"
+              },
+              "canEnableInheritedPermissions": {
+                "type": "boolean"
+              },
+              "canListChildren": {
+                "type": "boolean"
+              },
+              "canModifyContent": {
+                "type": "boolean"
+              },
+              "canModifyContentRestriction": {
+                "type": "boolean"
+              },
+              "canModifyEditorContentRestriction": {
+                "type": "boolean"
+              },
+              "canModifyLabels": {
+                "type": "boolean"
+              },
+              "canModifyOwnerContentRestriction": {
+                "type": "boolean"
+              },
+              "canMoveChildrenOutOfDrive": {
+                "type": "boolean"
+              },
+              "canMoveChildrenOutOfTeamDrive": {
+                "type": "boolean"
+              },
+              "canMoveChildrenWithinDrive": {
+                "type": "boolean"
+              },
+              "canMoveChildrenWithinTeamDrive": {
+                "type": "boolean"
+              },
+              "canMoveItemIntoTeamDrive": {
+                "type": "boolean"
+              },
+              "canMoveItemOutOfDrive": {
+                "type": "boolean"
+              },
+              "canMoveItemOutOfTeamDrive": {
+                "type": "boolean"
+              },
+              "canMoveItemWithinDrive": {
+                "type": "boolean"
+              },
+              "canMoveItemWithinTeamDrive": {
+                "type": "boolean"
+              },
+              "canMoveTeamDriveItem": {
+                "type": "boolean"
+              },
+              "canReadDrive": {
+                "type": "boolean"
+              },
+              "canReadLabels": {
+                "type": "boolean"
+              },
+              "canReadRevisions": {
+                "type": "boolean"
+              },
+              "canReadTeamDrive": {
+                "type": "boolean"
+              },
+              "canRemoveChildren": {
+                "type": "boolean"
+              },
+              "canRemoveContentRestriction": {
+                "type": "boolean"
+              },
+              "canRemoveMyDriveParent": {
+                "type": "boolean"
+              },
+              "canRename": {
+                "type": "boolean"
+              },
+              "canShare": {
+                "type": "boolean"
+              },
+              "canStartApproval": {
+                "type": "boolean"
+              },
+              "canTrash": {
+                "type": "boolean"
+              },
+              "canTrashChildren": {
+                "type": "boolean"
+              },
+              "canUntrash": {
+                "type": "boolean"
+              }
+            },
+            "type": "object"
+          },
+          "clientEncryptionDetails": {
+            "properties": {
+              "decryptionMetadata": {
+                "properties": {
+                  "aes256GcmChunkSize": {
+                    "type": "string"
+                  },
+                  "encryptionResourceKeyHash": {
+                    "type": "string"
+                  },
+                  "jwt": {
+                    "type": "string"
+                  },
+                  "kaclsId": {
+                    "type": "string"
+                  },
+                  "kaclsName": {
+                    "type": "string"
+                  },
+                  "keyFormat": {
+                    "type": "string"
+                  },
+                  "wrappedKey": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "encryptionState": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "contentHints": {
+            "properties": {
+              "indexableText": {
+                "type": "string"
+              },
+              "thumbnail": {
+                "properties": {
+                  "image": {
+                    "type": "string"
+                  },
+                  "mimeType": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "contentRestrictions": {
+            "items": {
+              "properties": {
+                "ownerRestricted": {
+                  "type": "boolean"
+                },
+                "readOnly": {
+                  "type": "boolean"
+                },
+                "reason": {
+                  "type": "string"
+                },
+                "restrictingUser": {
+                  "properties": {
+                    "displayName": {
+                      "type": "string"
+                    },
+                    "emailAddress": {
+                      "type": "string"
+                    },
+                    "kind": {
+                      "type": "string"
+                    },
+                    "me": {
+                      "type": "boolean"
+                    },
+                    "permissionId": {
+                      "type": "string"
+                    },
+                    "photoLink": {
+                      "type": "string"
+                    }
+                  },
+                  "type": "object"
+                },
+                "restrictionTime": {
+                  "type": "string"
+                },
+                "systemRestricted": {
+                  "type": "boolean"
+                },
+                "type": {
+                  "type": "string"
+                }
+              },
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "copyRequiresWriterPermission": {
+            "type": "boolean"
+          },
+          "createdTime": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "downloadRestrictions": {
+            "properties": {
+              "effectiveDownloadRestrictionWithContext": {
+                "properties": {
+                  "restrictedForReaders": {
+                    "type": "boolean"
+                  },
+                  "restrictedForWriters": {
+                    "type": "boolean"
+                  }
+                },
+                "type": "object"
+              },
+              "itemDownloadRestriction": {
+                "properties": {
+                  "restrictedForReaders": {
+                    "type": "boolean"
+                  },
+                  "restrictedForWriters": {
+                    "type": "boolean"
+                  }
+                },
+                "type": "object"
+              }
+            },
+            "type": "object"
+          },
+          "driveId": {
+            "type": "string"
+          },
+          "explicitlyTrashed": {
+            "type": "boolean"
+          },
+          "exportLinks": {
+            "type": "object"
+          },
+          "fileExtension": {
+            "type": "string"
+          },
+          "folderColorRgb": {
+            "type": "string"
+          },
+          "fullFileExtension": {
+            "type": "string"
+          },
+          "hasAugmentedPermissions": {
+            "type": "boolean"
+          },
+          "hasThumbnail": {
+            "type": "boolean"
+          },
+          "headRevisionId": {
+            "type": "string"
+          },
+          "iconLink": {
+            "type": "string"
+          },
+          "id": {
+            "type": "string"
+          },
+          "imageMediaMetadata": {
+            "properties": {
+              "aperture": {
+                "type": "number"
+              },
+              "cameraMake": {
+                "type": "string"
+              },
+              "cameraModel": {
+                "type": "string"
+              },
+              "colorSpace": {
+                "type": "string"
+              },
+              "exposureBias": {
+                "type": "number"
+              },
+              "exposureMode": {
+                "type": "string"
+              },
+              "exposureTime": {
+                "type": "number"
+              },
+              "flashUsed": {
+                "type": "boolean"
+              },
+              "focalLength": {
+                "type": "number"
+              },
+              "height": {
+                "type": "integer"
+              },
+              "isoSpeed": {
+                "type": "integer"
+              },
+              "lens": {
+                "type": "string"
+              },
+              "location": {
+                "properties": {
+                  "altitude": {
+                    "type": "number"
+                  },
+                  "latitude": {
+                    "type": "number"
+                  },
+                  "longitude": {
+                    "type": "number"
+                  }
+                },
+                "type": "object"
+              },
+              "maxApertureValue": {
+                "type": "number"
+              },
+              "meteringMode": {
+                "type": "string"
+              },
+              "rotation": {
+                "type": "integer"
+              },
+              "sensor": {
+                "type": "string"
+              },
+              "subjectDistance": {
+                "type": "integer"
+              },
+              "time": {
+                "type": "string"
+              },
+              "whiteBalance": {
+                "type": "string"
+              },
+              "width": {
+                "type": "integer"
+              }
+            },
+            "type": "object"
+          },
+          "inheritedPermissionsDisabled": {
+            "type": "boolean"
+          },
+          "isAppAuthorized": {
+            "type": "boolean"
+          },
+          "kind": {
+            "type": "string"
+          },
+          "labelInfo": {
+            "properties": {
+              "labels": {
+                "items": {
+                  "properties": {
+                    "fields": {
+                      "type": "object"
+                    },
+                    "id": {
+                      "type": "string"
+                    },
+                    "kind": {
+                      "type": "string"
+                    },
+                    "revisionId": {
+                      "type": "string"
+                    }
+                  },
+                  "type": "object"
+                },
+                "type": "array"
+              }
+            },
+            "type": "object"
+          },
+          "lastModifyingUser": {
+            "properties": {
+              "displayName": {
+                "type": "string"
+              },
+              "emailAddress": {
+                "type": "string"
+              },
+              "kind": {
+                "type": "string"
+              },
+              "me": {
+                "type": "boolean"
+              },
+              "permissionId": {
+                "type": "string"
+              },
+              "photoLink": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "linkShareMetadata": {
+            "properties": {
+              "securityUpdateEligible": {
+                "type": "boolean"
+              },
+              "securityUpdateEnabled": {
+                "type": "boolean"
+              }
+            },
+            "type": "object"
+          },
+          "md5Checksum": {
+            "type": "string"
+          },
+          "mimeType": {
+            "type": "string"
+          },
+          "modifiedByMe": {
+            "type": "boolean"
+          },
+          "modifiedByMeTime": {
+            "type": "string"
+          },
+          "modifiedTime": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "originalFilename": {
+            "type": "string"
+          },
+          "ownedByMe": {
+            "type": "boolean"
+          },
+          "owners": {
+            "items": {
+              "properties": {
+                "displayName": {
+                  "type": "string"
+                },
+                "emailAddress": {
+                  "type": "string"
+                },
+                "kind": {
+                  "type": "string"
+                },
+                "me": {
+                  "type": "boolean"
+                },
+                "permissionId": {
+                  "type": "string"
+                },
+                "photoLink": {
+                  "type": "string"
+                }
+              },
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "parents": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "permissionIds": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "permissions": {
+            "items": {
+              "properties": {
+                "allowFileDiscovery": {
+                  "type": "boolean"
+                },
+                "deleted": {
+                  "type": "boolean"
+                },
+                "displayName": {
+                  "type": "string"
+                },
+                "domain": {
+                  "type": "string"
+                },
+                "emailAddress": {
+                  "type": "string"
+                },
+                "expirationTime": {
+                  "type": "string"
+                },
+                "id": {
+                  "type": "string"
+                },
+                "inheritedPermissionsDisabled": {
+                  "type": "boolean"
+                },
+                "kind": {
+                  "type": "string"
+                },
+                "pendingOwner": {
+                  "type": "boolean"
+                },
+                "permissionDetails": {
+                  "items": {
+                    "properties": {
+                      "inherited": {
+                        "type": "boolean"
+                      },
+                      "inheritedFrom": {
+                        "type": "string"
+                      },
+                      "permissionType": {
+                        "type": "string"
+                      },
+                      "role": {
+                        "type": "string"
+                      }
+                    },
+                    "type": "object"
+                  },
+                  "type": "array"
+                },
+                "photoLink": {
+                  "type": "string"
+                },
+                "role": {
+                  "type": "string"
+                },
+                "teamDrivePermissionDetails": {
+                  "items": {
+                    "properties": {
+                      "inherited": {
+                        "type": "boolean"
+                      },
+                      "inheritedFrom": {
+                        "type": "string"
+                      },
+                      "role": {
+                        "type": "string"
+                      },
+                      "teamDrivePermissionType": {
+                        "type": "string"
+                      }
+                    },
+                    "type": "object"
+                  },
+                  "type": "array"
+                },
+                "type": {
+                  "type": "string"
+                },
+                "view": {
+                  "type": "string"
+                }
+              },
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "properties": {
+            "type": "object"
+          },
+          "quotaBytesUsed": {
+            "type": "string"
+          },
+          "resourceKey": {
+            "type": "string"
+          },
+          "sha1Checksum": {
+            "type": "string"
+          },
+          "sha256Checksum": {
+            "type": "string"
+          },
+          "shared": {
+            "type": "boolean"
+          },
+          "sharedWithMeTime": {
+            "type": "string"
+          },
+          "sharingUser": {
+            "properties": {
+              "displayName": {
+                "type": "string"
+              },
+              "emailAddress": {
+                "type": "string"
+              },
+              "kind": {
+                "type": "string"
+              },
+              "me": {
+                "type": "boolean"
+              },
+              "permissionId": {
+                "type": "string"
+              },
+              "photoLink": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "shortcutDetails": {
+            "properties": {
+              "targetId": {
+                "type": "string"
+              },
+              "targetMimeType": {
+                "type": "string"
+              },
+              "targetResourceKey": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "size": {
+            "type": "string"
+          },
+          "spaces": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "starred": {
+            "type": "boolean"
+          },
+          "teamDriveId": {
+            "type": "string"
+          },
+          "thumbnailLink": {
+            "type": "string"
+          },
+          "thumbnailVersion": {
+            "type": "string"
+          },
+          "trashed": {
+            "type": "boolean"
+          },
+          "trashedTime": {
+            "type": "string"
+          },
+          "trashingUser": {
+            "properties": {
+              "displayName": {
+                "type": "string"
+              },
+              "emailAddress": {
+                "type": "string"
+              },
+              "kind": {
+                "type": "string"
+              },
+              "me": {
+                "type": "boolean"
+              },
+              "permissionId": {
+                "type": "string"
+              },
+              "photoLink": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "version": {
+            "type": "string"
+          },
+          "videoMediaMetadata": {
+            "properties": {
+              "durationMillis": {
+                "type": "string"
+              },
+              "height": {
+                "type": "integer"
+              },
+              "width": {
+                "type": "integer"
+              }
+            },
+            "type": "object"
+          },
+          "viewedByMe": {
+            "type": "boolean"
+          },
+          "viewedByMeTime": {
+            "type": "string"
+          },
+          "viewersCanCopyContent": {
+            "type": "boolean"
+          },
+          "webContentLink": {
+            "type": "string"
+          },
+          "webViewLink": {
+            "type": "string"
+          },
+          "writersCanShare": {
+            "type": "boolean"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "incompleteSearch": {
+      "type": "boolean"
+    },
+    "kind": {
+      "type": "string"
+    },
+    "nextPageToken": {
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

First observedOct 26, 2026

TDQS

B3.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries the full load. It usefully discloses the default-inclusion-of-trashed behavior and that the call is HTTP GET returning JSON, but says nothing about pagination semantics (pageSize default of 100, nextPageToken continuation) or required auth/scope for a 19-parameter list endpoint. That leaves meaningful behavior undisclosed for a tool with zero annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Core content (list behavior, trashed default, q syntax, docs link) is front-loaded, which is good. But a chunk of it is generic boilerplate about `body_file` and typed-vs-`params` precedence that is irrelevant to a GET, and the appended list of 13 sibling names adds length without routing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return shape need not be described, and the trashed-default caveat is the key behavioral trap. Still, for a 19-parameter paginated list endpoint with no annotations, the description omits pagination guidance and scope/corpus selection (driveId, corpora, supportsAllDrives), which are the main ways an agent will call this incorrectly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3, but the description adds real value by explaining that `q` combines search terms and by giving a working example (`trashed=false`) — a filter that isn't even a typed parameter and must go through `query`/`params`. That is guidance the schema alone does not supply.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ("Lists the user's files") and adds that `q` is the filter query, so the agent knows this is a listing/search-over-files operation. The trailing sibling enumeration ('copy, create, delete, download...') names other tools without differentiating scope, so it doesn't fully separate this from other read paths like drive.files.get.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives one concrete usage rule — results include trashed files by default, add `trashed=false` to exclude them — which is genuinely actionable. But it never states when to use this over drive.files.get for a single file, nor when q-search is preferable to a plain listing, leaving the main routing decision implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server