Enables creation, reading, editing, and formatting of Google Docs documents, including support for multi-tab documents, tables, images, comments, bulk operations, and markdown import/export.
Provides tools for managing Google Drive files and folders, including listing, searching, creating folders, uploading files and images, and resource-based file uploads through shared blob storage.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Google Docs MCP Server create a new document titled 'Project Plan' with my meeting notes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Docker configuration for running the Google Docs MCP Server in a container.
This server provides Model Context Protocol (MCP) tools for interacting with Google Docs and Google Drive, enabling AI assistants like Claude to read, write, and manage your documents.
Create blank documents - Create new Google Documents from scratch
Import from Markdown - Create Google Docs with content imported from markdown using Google Drive API's native markdown import (July 2024+). Supports standard markdown syntax with formatting handled by Google's native parser.
Read documents - Export content as text, JSON, or markdown (markdown export uses Google Drive API's native export)
Edit documents - Insert, append, and delete text
Format text - Apply character and paragraph styles (bold, italic, colors, fonts, alignment, etc.)
Manage structure - Insert tables, page breaks, and images
Handle tabs - List and work with multi-tab documents
Bulk operations - Execute multiple document operations in a single batched API call for 5-10x faster performance
List, add, reply to, resolve, and delete comments on documents
List, search, and get document metadata
Create and manage folders
Upload files and images
Resource-based uploads - Upload files and images using resource identifiers from shared blob storage (for integration with other MCP servers)
Related MCP server: Google Docs MCP
Docker and Docker Compose installed
A Google Account
Google Cloud Project with OAuth credentials
Go to the Google Cloud Console
Create or select a project:
Click the project dropdown and select "NEW PROJECT"
Name it (e.g., "Google Docs MCP") and click "CREATE"
Enable required APIs:
Go to "APIs & Services" > "Library"
Search for and enable Google Docs API
Search for and enable Google Drive API
Configure OAuth Consent Screen:
Go to "APIs & Services" > "OAuth consent screen"
Select "External" and click "CREATE"
Fill in:
App name: e.g., "Google Docs MCP Server"
User support email: your email
Developer contact: your email
Click "SAVE AND CONTINUE"
Click "ADD OR REMOVE SCOPES" and add:
https://www.googleapis.com/auth/documents
https://www.googleapis.com/auth/drive.file
Click "UPDATE" then "SAVE AND CONTINUE"
Add your Google email as a Test User
Click "SAVE AND CONTINUE"
Create OAuth Credentials:
Go to "APIs & Services" > "Credentials"
Click "+ CREATE CREDENTIALS" > "OAuth client ID"
Select "Desktop app" as the application type
Name it (e.g., "MCP Docker Client")
Click "CREATE"
Download the JSON file
Create a credentials directory in this project:
mkdir -p credentialsCopy your downloaded OAuth JSON file:
cp ~/Downloads/client_secret_*.json credentials/credentials.jsondocker-compose buildThe first time you run the server, you need to authenticate with Google to generate a token. The authentication uses a loopback OAuth flow with automatic port discovery.
How it works:
The container discovers its published port via Docker API
OAuth callback redirects to the discovered host port automatically
No manual port configuration needed
Important: Create an empty token.json file before running if it doesn't exist:
touch credentials/token.jsonRun the container (Docker will assign an ephemeral port automatically):
docker run -it --rm \
-p 3000 \
-v $(pwd)/credentials:/workspace/credentials \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
workspace-google-docs-mcp:latestNote: On Windows, use full paths instead of $(pwd):
docker run -it --rm ^
-p 3000 ^
-v C:/path/to/google-docs-mcp/credentials:/workspace/credentials ^
-v /var/run/docker.sock:/var/run/docker.sock:ro ^
workspace-google-docs-mcp:latestThe container will detect its published port via Docker API and display it in the logs
The server will output an authorization URL
Copy the URL and open it in your browser
Log in with your Google account (the one added as a Test User)
Click "Allow" to grant permissions
Google will redirect to the discovered port - the container captures this automatically
You'll see "Authentication Successful!" in your browser
The token.json file will be saved to your credentials/ directory
Press Ctrl+C to stop the container
Alternatively, use docker-compose:
docker-compose updocker-compose up -dThe MCP server is now running and ready to accept connections.
Add this to your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
Run the MCP server in a Docker container. This requires mounting the credentials and token files:
{
"mcpServers": {
"google-docs": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-p",
"3000",
"-v",
"C:/path/to/google-docs-mcp/credentials:/workspace/credentials",
"-v",
"/var/run/docker.sock:/var/run/docker.sock:ro",
"-v",
"blob-storage:/mnt/blob-storage",
"-e",
"BLOB_STORAGE_ROOT=/mnt/blob-storage",
"-e",
"BLOB_STORAGE_MAX_SIZE_MB=100",
"-e",
"BLOB_STORAGE_TTL_HOURS=24",
"workspace-google-docs-mcp:latest"
]
}
}
}Configuration notes:
-p 3000 - Ephemeral port binding (Docker assigns available host port automatically)
The first -v mount maps your local credentials/ directory (containing both credentials.json and token.json) to /workspace/credentials/ in the container
The second -v mount provides Docker socket access for automatic port discovery
Windows: Docker Desktop automatically translates /var/run/docker.sock to the Windows named pipe
Linux/macOS: Uses the native Docker socket at /var/run/docker.sock
Important: Ensure "Expose daemon on tcp://localhost:2375 without TLS" is NOT enabled in Docker Desktop settings (it's a security risk and not needed)
The third -v mount creates a shared blob storage volume for resource-based file uploads (optional, only needed if using resource-based upload features)
The -e flags set environment variables for blob storage configuration (optional, defaults shown)
Note: Adjust the path (C:/path/to/google-docs-mcp/credentials) to match your local credentials directory. On Linux/macOS, use Unix-style paths (e.g., /home/user/google-docs-mcp/credentials).
Optional: Remove the blob storage volume mount and environment variables if you don't need resource-based upload features.
If you prefer to keep the container running in the background with docker-compose up -d:
{
"mcpServers": {
"google-docs": {
"command": "docker",
"args": [
"exec",
"-i",
"google-docs-mcp-server",
"uv",
"run",
"google-docs-mcp"
]
}
}
}Note: The container must be running before starting Claude Desktop.
Restart Claude Desktop after updating the configuration.
.
├── Dockerfile # Docker image definition (dev + production)
├── docker-compose.yml # Docker Compose for production
├── docker-compose.devcontainer.yml # Docker Compose for VS Code devcontainer
├── .devcontainer/
│ └── devcontainer.json # VS Code devcontainer configuration
├── src/
│ └── google_docs_mcp/ # Python source code
│ ├── server.py # Main MCP server entry point
│ ├── auth.py # OAuth2 authentication (loopback flow)
│ └── api/ # API modules (documents, comments, drive)
├── tests/ # Test files
├── credentials/ # Your Google OAuth credentials (gitignored)
│ ├── credentials.json # OAuth client credentials
│ └── token.json # OAuth access token (generated after auth)
├── pyproject.toml # Python project configuration
├── .gitignore # Git ignore rules
└── README.md # This fileThe project includes a devcontainer configuration for VS Code:
Open the project in VS Code
When prompted, click "Reopen in Container" (or use Command Palette: "Dev Containers: Reopen in Container")
VS Code will build the container and install dependencies automatically
The devcontainer includes:
Python 3.12 with uv package manager
Docker CLI (Docker-outside-of-Docker support)
Node.js 20 and Claude Code CLI
VS Code extensions: Python, Pylance, debugpy, Ruff, Claude Code
Port 3000 forwarded for OAuth loopback callback
# Install dependencies
uv sync
# Run the server
uv run google-docs-mcp
# Run tests
uv run pytestThis server uses Docker API to automatically discover its published port for OAuth callbacks. This enables:
Ephemeral port bindings - Docker can assign any available host port
No port conflicts - Multiple instances can run simultaneously
Automatic configuration - No manual port setup required
Container starts with ephemeral port binding (e.g., -p 3000)
Docker assigns an available host port (e.g., 32768)
Server discovers the mapping via Docker API (reads /proc/self/cgroup and queries Docker socket)
OAuth redirect URI uses the discovered host port (http://localhost:32768)
Authentication succeeds automatically
Docker socket must be mounted: -v /var/run/docker.sock:/var/run/docker.sock:ro
Python docker package must be installed (included in dependencies)
If Docker API is unavailable (socket not mounted or not running in Docker):
Falls back to default port 3000
Logs a warning to stderr
Continues normally with static port
"Docker API unavailable" or "Connection aborted" error:
Windows with Docker Desktop:
Ensure Docker Desktop is running and fully started
In Docker Desktop Settings → General, verify "Expose daemon on tcp://localhost:2375 without TLS" is OFF (unchecked)
The socket mount -v /var/run/docker.sock:/var/run/docker.sock:ro should work automatically (Docker Desktop translates it)
If the error persists, try restarting Docker Desktop
As a workaround, you can omit the Docker socket mount - the server will fall back to port 3000 (but you'll need to use -p 3000:3000 instead of -p 3000)
Linux/macOS:
Ensure Docker socket is mounted in your configuration
Check socket permissions: ls -l /var/run/docker.sock
Add your user to the docker group: sudo usermod -aG docker $USER (then log out and back in)
"No port mapping found" warning:
Verify port is published in docker run/compose configuration
Check with: docker port <container_name>
Authentication still fails:
Check container logs: docker logs <container_name>
Verify OAuth credentials in Google Cloud Console
Ensure redirect URI matches what Google expects
Command | Description |
| Build the Docker image |
| Start the server in background |
| Stop the server |
| View server logs |
| Run auth service interactively |
This MCP server integrates with mcp_mapped_resource_lib to support resource-based file uploads. This enables efficient file sharing between multiple MCP servers through a shared Docker volume.
Traditional MCP file transfers require encoding files as base64 and passing them through the MCP protocol, which can be inefficient for large files. With resource-based uploads:
Other MCP servers upload files to a shared blob storage volume and return a resource identifier (e.g., blob://1733437200-a3f9d8c2b1e4f6a7.png)
This server can directly access those files via the resource identifier and upload them to Google Drive
No file data is transferred through the MCP protocol - only the small resource identifier
upload_image_to_drive_from_resource - Upload an image to Drive using a resource ID
upload_file_to_drive_from_resource - Upload any file to Drive using a resource ID
insert_image_from_resource - Insert an image into a document using a resource ID
Add a shared volume for blob storage in your docker-compose.yml:
services:
google-docs-mcp:
# ... existing config ...
volumes:
- ./credentials:/workspace/credentials
- blob-storage:/mnt/blob-storage # Add this line
environment:
- PYTHONUNBUFFERED=1
- BLOB_STORAGE_ROOT=/mnt/blob-storage # Required
- BLOB_STORAGE_MAX_SIZE_MB=100 # Optional: max file size (default: 100)
- BLOB_STORAGE_TTL_HOURS=24 # Optional: time-to-live (default: 24)
volumes:
blob-storage:
driver: localConfiguration Options:
BLOB_STORAGE_ROOT - Required. Path to the blob storage directory
BLOB_STORAGE_MAX_SIZE_MB - Optional. Maximum file size in MB (default: 100)
BLOB_STORAGE_TTL_HOURS - Optional. Time-to-live for blobs in hours (default: 24). Blobs older than this will be automatically cleaned up.
When using resource-based uploads, update your claude_desktop_config.json to mount the blob storage volume:
{
"mcpServers": {
"google-docs": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-p",
"3000:3000",
"-v",
"C:/path/to/google-docs-mcp/credentials:/workspace/credentials",
"-v",
"blob-storage:/mnt/blob-storage",
"-e",
"BLOB_STORAGE_ROOT=/mnt/blob-storage",
"-e",
"BLOB_STORAGE_MAX_SIZE_MB=100",
"-e",
"BLOB_STORAGE_TTL_HOURS=24",
"workspace-google-docs-mcp:latest"
]
}
}
}Note: Replace C:/path/to/google-docs-mcp/credentials with your actual credentials path. On Linux/macOS, use Unix-style paths.
Configuration:
Adjust BLOB_STORAGE_MAX_SIZE_MB to set the maximum file size (in MB)
Adjust BLOB_STORAGE_TTL_HOURS to control how long blobs are retained before automatic cleanup
Other MCP servers can use the same volume. Example configuration:
{
"mcpServers": {
"google-docs": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-p", "3000:3000",
"-v", "C:/path/to/google-docs-mcp/credentials:/workspace/credentials",
"-v", "blob-storage:/mnt/blob-storage",
"-e", "BLOB_STORAGE_ROOT=/mnt/blob-storage",
"-e", "BLOB_STORAGE_MAX_SIZE_MB=100",
"-e", "BLOB_STORAGE_TTL_HOURS=24",
"workspace-google-docs-mcp:latest"
]
},
"other-mcp-server": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-v", "blob-storage:/mnt/blob-storage:ro",
"other-mcp-server:latest"
]
}
}
}Important: The volume name (blob-storage) must be the same across all MCP servers that need to share resources.
With another MCP server that has blob upload capabilities:
Other MCP server uploads a file to blob storage:
User: Upload this image to blob storage
Other Server: Uploaded! Resource ID: blob://1733437200-a3f9d8c2b1e4f6a7.pngThis server uploads to Google Drive using the resource ID:
User: Upload that image to my Google Drive using resource blob://1733437200-a3f9d8c2b1e4f6a7.png
Google Docs Server: Successfully uploaded image "photo.png" from resource blob://1733437200-a3f9d8c2b1e4f6a7.pngResource identifiers follow the pattern: blob://TIMESTAMP-HASH.EXT
TIMESTAMP - Unix timestamp when the file was uploaded
HASH - SHA256 hash (truncated) for uniqueness
EXT - Original file extension
Example: blob://1733437200-a3f9d8c2b1e4f6a7.png
The bulk_update_google_doc tool allows you to execute multiple document operations in a single batched API call, providing 5-10x performance improvement over individual tool calls.
When making multiple changes to a document (formatting, inserting content, adding tables, etc.), each individual tool call requires a separate network round-trip to Google's API. This creates significant latency:
Before (individual calls):
10 formatting operations = 10 API calls = ~5-10 seconds
After (bulk operations):
10 formatting operations = 1 batched API call = ~0.5-1 second
The bulk tool supports all document manipulation operations:
insert_text - Insert text at a specific index
delete_range - Delete content in a range
apply_text_style - Apply character-level formatting (bold, italic, colors, etc.)
apply_paragraph_style - Apply paragraph-level formatting (alignment, headings, spacing, etc.)
insert_table - Insert a table
insert_page_break - Insert a page break
insert_image_from_url - Insert an image from a URL
Here's an example of creating a formatted document with a title, introduction, table, and styled text in a single API call:
{
"document_id": "your-document-id-here",
"operations": [
{
"type": "insert_text",
"text": "Project Status Report\n\n",
"index": 1
},
{
"type": "apply_paragraph_style",
"start_index": 1,
"end_index": 23,
"named_style_type": "HEADING_1",
"alignment": "CENTER"
},
{
"type": "insert_text",
"text": "Executive Summary\n\n",
"index": 23
},
{
"type": "apply_paragraph_style",
"start_index": 23,
"end_index": 42,
"named_style_type": "HEADING_2"
},
{
"type": "insert_text",
"text": "This report provides an overview of project progress and key metrics.\n\n",
"index": 42
},
{
"type": "insert_text",
"text": "Key Metrics\n\n",
"index": 113
},
{
"type": "apply_paragraph_style",
"start_index": 113,
"end_index": 126,
"named_style_type": "HEADING_2"
},
{
"type": "insert_table",
"rows": 4,
"columns": 3,
"index": 126
},
{
"type": "insert_text",
"text": "\n\nConclusion\n",
"index": 127
},
{
"type": "apply_text_style",
"text_to_find": "Conclusion",
"match_instance": 1,
"bold": true,
"font_size": 14
}
]
}Each operation is a dictionary with a type field and operation-specific parameters:
text (string): Text to insert
index (integer): Position to insert at (1-based)
tab_id (string, optional): Tab ID for multi-tab documents
start_index (integer): Start of range (1-based, inclusive)
end_index (integer): End of range (1-based, exclusive)
tab_id (string, optional): Tab ID
Range targeting (choose one):
start_index and end_index (integers): Direct range specification
text_to_find (string) and match_instance (integer): Find specific text
Style properties:
bold, italic, underline, strikethrough (boolean)
font_size (float): Font size in points
font_family (string): Font name (e.g., "Arial", "Times New Roman")
foreground_color, background_color (string): Hex color (e.g., "#FF0000")
link_url (string): URL for hyperlink
Range targeting (choose one):
start_index and end_index (integers): Direct range specification
text_to_find (string) and match_instance (integer): Find text, format its paragraph
index_within_paragraph (integer): Format paragraph containing this index
Style properties:
alignment (string): "START", "END", "CENTER", "JUSTIFIED"
indent_start, indent_end (float): Indentation in points
space_above, space_below (float): Spacing in points
named_style_type (string): "NORMAL_TEXT", "HEADING_1" through "HEADING_6", "TITLE", "SUBTITLE"
keep_with_next (boolean): Keep paragraph with next
rows (integer): Number of rows
columns (integer): Number of columns
index (integer): Position to insert (1-based)
index (integer): Position to insert (1-based)
image_url (string): Publicly accessible image URL
index (integer): Position to insert (1-based)
width, height (float, optional): Dimensions in points
Maximum 500 operations per call (automatically batched into groups of 50 for Google API)
Operations are executed in the order provided
All operations must be valid before any are executed (fail-fast validation)
Group related operations: Combine all changes to a document in a single bulk call
Use index-based targeting when possible: Text-finding operations require fetching the document first
Order matters: Structure your operations to account for index changes (e.g., insert text before applying formatting to that text)
This server uses Google Drive API's native markdown import/export (available since July 2024), which provides reliable conversion with Google's official parser.
Images in markdown export: Images are exported as base64 data URLs (a known Google limitation). For sharing documents, use the original Google Docs file.
Tab support: The markdown export API exports the entire document. Individual tab export is not supported - if you specify a tab_id, you'll get a warning and the entire document will be exported.
Conversion fidelity: Formatting quality depends on Google's implementation. Complex Google Docs features may not have exact markdown equivalents.
API requirement: Requires Google Drive API access in addition to Google Docs API (both should be enabled during setup).
Never commit credentials.json or token.json to version control
The .gitignore file is configured to exclude these files
Treat these files like passwords - they grant access to your Google account
The token.json file allows the server to access your Google account without re-authentication
"credentials.json not found" error:
Ensure you've placed credentials.json in the credentials/ directory
Check the file is named exactly credentials.json
Authentication fails:
Verify you added your email as a Test User in Google Cloud Console
Ensure you enabled both Google Docs API and Google Drive API
Docker container won't start:
Check that both credentials.json and token.json exist in credentials/
Run docker-compose logs to see error messages
Claude Desktop shows "Failed to connect":
Ensure the container is running: docker-compose ps
Verify the container name is google-docs-mcp-server
Try restarting Claude Desktop
This Docker configuration is provided under the MIT License. The underlying google-docs-mcp server is licensed separately.
Add a comment anchored to a specific text range in the document.
NOTE: Due to Google API limitations, comments created programmatically appear in the 'All Comments' list but may not be visibly anchored in the UI.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document | |
| start_index | Yes | Starting index of the text range (inclusive, 1-based) | |
| end_index | Yes | Ending index of the text range (exclusive) | |
| comment_text | Yes | The content of the comment |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively discloses a critical behavioral trait: 'comments created programmatically appear in the 'All Comments' list but may not be visibly anchored in the UI due to Google API limitations.' This adds valuable context beyond basic functionality, though it could mention permissions or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded: the first sentence states the core purpose clearly, and the second sentence adds essential behavioral context without redundancy. Every sentence earns its place, making it efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (a write operation with 4 parameters), no annotations, but with an output schema (implied by 'Has output schema: true'), the description is reasonably complete. It covers purpose and a key behavioral limitation, though it could benefit from mentioning authentication needs or response format, which the output schema may address.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all four parameters thoroughly. The description does not add any parameter-specific semantics beyond what the schema provides (e.g., it doesn't clarify index formatting or comment text constraints). Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Add a comment') and resource ('anchored to a specific text range in the document'), distinguishing it from sibling tools like 'get_comment', 'list_comments', 'delete_comment', and 'reply_to_comment'. It precisely defines what the tool does without being vague or tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by specifying 'anchored to a specific text range', but does not explicitly state when to use this tool versus alternatives like 'reply_to_comment' or general comment management tools. No explicit exclusions or prerequisites are provided, leaving usage guidance at an implied level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Append text to the very end of a Google Document or specific tab.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document | |
| text_to_append | Yes | The text to add to the end of the document | |
| add_newline_if_needed | No | Automatically add a newline before the appended text if needed | |
| tab_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions appending 'to the very end' and 'specific tab' which adds some context, but doesn't address critical behavioral aspects: whether this requires edit permissions, if it's idempotent, what happens on failure, or what the output contains. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding how the tool behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that immediately states the core functionality. Every word earns its place - 'Append text' specifies the action, 'to the very end' clarifies positioning, 'Google Document' identifies the resource, and 'or specific tab' adds important scope information. There's zero waste or redundancy in this compact description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a mutation tool with no annotations but with an output schema (which handles return values), the description is minimally adequate. It covers the basic what and where, but lacks important context about permissions, error conditions, and when to use versus alternatives. The presence of an output schema means the description doesn't need to explain return values, but it should provide more behavioral context for a write operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75% (3 of 4 parameters have descriptions), so the baseline is 3. The description adds minimal value beyond the schema - it mentions 'specific tab' which relates to the 'tab_id' parameter, but doesn't explain what tabs are or when they're used. It doesn't clarify the relationship between document_id and tab_id, or provide examples of valid document IDs. The description doesn't compensate for the 25% coverage gap in a meaningful way.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Append text') and target resource ('Google Document or specific tab'), making the purpose immediately understandable. It doesn't explicitly distinguish from siblings like 'insert_text' or 'replace_all_text', but the 'append' verb implies end-of-document positioning. The description is specific enough to understand what the tool does without being tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'insert_text' (which might allow positioning anywhere) or 'replace_all_text'. It mentions 'specific tab' but doesn't explain when tab targeting is needed versus regular document appending. There's no mention of prerequisites, permissions required, or common use cases for this operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply paragraph-level formatting (alignment, spacing, headings, etc.).
Target can be specified by:
Range: Provide start_index and end_index
Text search: Provide text_to_find (styles the containing paragraph)
Index: Provide index_within_paragraph
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document | |
| alignment | No | ||
| indent_start | No | ||
| indent_end | No | ||
| space_above | No | ||
| space_below | No | ||
| named_style_type | No | ||
| keep_with_next | No | ||
| start_index | No | ||
| end_index | No | ||
| text_to_find | No | ||
| match_instance | No | Which instance of text to target | |
| index_within_paragraph | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the tool applies formatting, implying a mutation operation, but doesn't disclose behavioral traits like whether changes are reversible, what permissions are required, how errors are handled, or what the output contains. The description adds some context about targeting methods but misses critical behavioral information for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and well-structured: a clear purpose statement followed by a bullet-point list of targeting methods. Every sentence earns its place, with no wasted words, and information is front-loaded for quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (13 parameters, mutation operation) and lack of annotations, the description is incomplete. It explains targeting methods well but omits details on formatting parameters, error conditions, and behavioral expectations. The presence of an output schema reduces the need to describe return values, but more context is needed for safe and effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (15%), but the description compensates well by explaining the semantics of targeting parameters: it clarifies that 'start_index' and 'end_index' define a range, 'text_to_find' styles the containing paragraph via text search, and 'index_within_paragraph' uses an index. This adds meaningful context beyond the sparse schema descriptions, though it doesn't cover formatting parameters like 'alignment' or 'named_style_type'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Apply paragraph-level formatting (alignment, spacing, headings, etc.)'. It specifies the verb ('apply') and resource ('paragraph-level formatting') with concrete examples. However, it doesn't explicitly differentiate from sibling tools like 'apply_text_style' or 'format_matching_text', which likely handle different formatting scopes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implied usage guidance by explaining three methods to target paragraphs (range, text search, index), which helps understand when to use specific parameters. However, it lacks explicit guidance on when to choose this tool over alternatives like 'apply_text_style' or 'bulk_update_google_doc', and doesn't mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply character-level formatting (bold, color, font, etc.) to text.
Target can be specified either by:
Range: Provide start_index and end_index
Text search: Provide text_to_find and optionally match_instance
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document | |
| bold | No | ||
| italic | No | ||
| underline | No | ||
| strikethrough | No | ||
| font_size | No | ||
| font_family | No | ||
| foreground_color | No | ||
| background_color | No | ||
| link_url | No | ||
| start_index | No | ||
| end_index | No | ||
| text_to_find | No | ||
| match_instance | No | Which instance of text to target (1st, 2nd, etc.) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but lacks critical behavioral details. It doesn't disclose that this is a mutation operation (applies formatting changes), potential side effects, permission requirements, error conditions, or how it interacts with existing formatting. The description only covers targeting methods without behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with two sentences that each earn their place. The first sentence states the core purpose, and the second explains the targeting methods. No wasted words, and information is front-loaded appropriately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (14 parameters, mutation operation) with no annotations and low schema coverage, the description is incomplete. While it explains targeting methods well, it lacks crucial context about mutation behavior, error handling, and interaction with other formatting tools. The presence of an output schema helps, but the description should do more for a formatting mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 14%, so the description must compensate. It adds significant value by explaining the two targeting approaches (range vs. text search) and their corresponding parameters, which clarifies the semantic relationship between start_index/end_index and text_to_find/match_instance. This goes well beyond the minimal schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('apply') and resource ('character-level formatting to text'), specifying formatting types like bold, color, font. It distinguishes from sibling tools like 'apply_paragraph_style' by focusing on character-level formatting, though it doesn't explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by explaining two targeting methods (range or text search), which suggests when to use each approach. However, it doesn't provide explicit guidance on when to use this tool versus alternatives like 'format_matching_text' or 'bulk_update_google_doc', nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute multiple document operations in a single batched API call for improved performance.
This tool allows you to perform many operations at once instead of making separate tool calls. Operations are batched into groups of up to 50 requests (Google Docs API limit) and executed sequentially. This significantly reduces latency when making complex document changes.
Performance: 5-10x faster than individual tool calls for multi-operation workflows.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document to update | |
| operations | Yes | List of operations to perform. Each operation is a dictionary with a 'type' field and operation-specific parameters. Supported operation types: 1. insert_text: Insert text at a specific index - text: Text to insert (string) - index: Position to insert at (1-based integer) - tab_id: Optional tab ID (string) 2. delete_range: Delete a range of content - start_index: Start of range (1-based, inclusive) - end_index: End of range (1-based, exclusive) - tab_id: Optional tab ID (string) 3. apply_text_style: Apply character-level formatting - Either (start_index, end_index) OR (text_to_find, match_instance) - Style properties: bold, italic, underline, strikethrough, font_size, font_family, foreground_color, background_color, link_url 4. apply_paragraph_style: Apply paragraph-level formatting - Either (start_index, end_index) OR (text_to_find, match_instance) OR index_within_paragraph - Style properties: alignment, indent_start, indent_end, space_above, space_below, named_style_type, keep_with_next 5. insert_table: Insert a table - rows: Number of rows (integer) - columns: Number of columns (integer) - index: Position to insert (1-based integer) 6. insert_page_break: Insert a page break - index: Position to insert (1-based integer) 7. insert_image_from_url: Insert an image from a URL - image_url: URL to the image (string) - index: Position to insert (1-based integer) - width: Optional width in points (float) - height: Optional height in points (float) Example: [ {"type": "insert_text", "text": "# Title\n\n", "index": 1}, {"type": "apply_paragraph_style", "start_index": 1, "end_index": 8, "named_style_type": "HEADING_1"}, {"type": "insert_text", "text": "Introduction text.\n", "index": 8}, {"type": "insert_table", "rows": 3, "columns": 2, "index": 27} ] | |
| tab_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well. It discloses key behavioral traits: batching up to 50 requests (API limit), sequential execution, performance improvement (5-10x faster), and that it's for document updates. It doesn't mention error handling, atomicity, or authentication requirements, but covers the essential operational characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded with the core purpose in the first sentence. Each subsequent sentence adds value: explaining the batching mechanism, performance benefits, and quantitative comparison. There's minimal redundancy, though the performance claim could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (batch operations with multiple parameter types) and no annotations, the description provides good context about the batching mechanism and performance benefits. Combined with the detailed input schema (67% coverage) and presence of an output schema, the overall documentation is quite complete. It could benefit from mentioning error handling or atomicity guarantees.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description doesn't directly discuss parameters, but the input schema has 67% coverage with detailed documentation of the 'operations' parameter including all supported operation types with examples. Since schema coverage is moderate (67%), the comprehensive schema documentation adequately compensates. The description's focus on batch execution context provides valuable semantic framing for the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Execute multiple document operations in a single batched API call for improved performance.' It specifies the verb ('execute'), resource ('document operations'), and distinguishes from siblings by emphasizing batch processing versus individual operations. The performance comparison further differentiates it from single-operation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: 'when making complex document changes' and for 'multi-operation workflows' where performance is important. It explicitly states the alternative ('instead of making separate tool calls') but doesn't specify when NOT to use it or name specific sibling alternatives for simple operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a copy of a file in Google Drive.
Returns the new file's ID and web link.
| Name | Required | Description | Default |
|---|---|---|---|
| file_id | Yes | The ID of the file to copy | |
| new_name | No | ||
| parent_folder_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions the return values (ID and web link), which adds some behavioral context beyond the basic action. However, it doesn't disclose critical traits like whether it requires specific permissions, if it preserves metadata, handles large files, or has rate limits—important for a mutation tool in Google Drive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste: the first states the purpose, the second specifies the return values. It's front-loaded and appropriately sized for a simple tool, with every sentence earning its place by adding value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a mutation tool with no annotations, 3 parameters, and an output schema (which likely covers return values), the description is moderately complete. It covers the basic action and outputs, but lacks details on permissions, error conditions, or sibling differentiation that would be helpful for an agent in this context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 33% (only 'file_id' has a description), so the description must compensate but doesn't add parameter details. It implies copying with optional naming and folder placement via the action, but doesn't explain 'new_name' or 'parent_folder_id' semantics beyond what the schema's null defaults suggest. With low coverage, this is a minimal baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a copy') and resource ('a file in Google Drive'), making the purpose immediately understandable. However, it doesn't differentiate this tool from potential alternatives like 'duplicate_file' or explain how it differs from 'move_file' or 'upload_file_to_drive' among the siblings, which would require a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. With sibling tools like 'move_file', 'create_folder', and various upload tools, the description doesn't indicate whether this is for duplicating within the same folder, creating backups, or other specific use cases. The agent must infer usage from the purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a bulleted or numbered list from a range of paragraphs.
Converts existing paragraphs within the specified range into a list. To create a nested list, use different nesting levels.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document | |
| start_index | Yes | Starting index of the range (inclusive, 1-based) | |
| end_index | Yes | Ending index of the range (exclusive) | |
| list_type | No | Type of list: 'UNORDERED' (bullets), 'ORDERED_DECIMAL' (1,2,3), 'ORDERED_ALPHA' (a,b,c), 'ORDERED_ROMAN' (i,ii,iii) | UNORDERED |
| nesting_level | No | Nesting level (0-8, where 0 is top level) | |
| tab_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions the tool 'Converts existing paragraphs' but does not disclose behavioral traits such as whether this is a destructive operation (overwrites content), requires specific permissions, or has rate limits. The description lacks details on error handling, response format, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with two sentences: the first states the purpose, and the second adds usage guidance for nesting. It is front-loaded with the core function and has zero waste, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (6 parameters, 3 required) and high schema coverage (83%), the description is mostly complete. It covers the main purpose and nesting usage. However, with no annotations and an output schema present (though not detailed here), it could benefit from more behavioral context, but the essentials are addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 83%, which is high, so the baseline is 3. The description adds minimal value beyond the schema: it implies 'range' relates to 'start_index' and 'end_index' and mentions 'nesting levels' for 'nesting_level', but does not explain parameter interactions or provide additional semantics like format constraints or examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Create a bulleted or numbered list from a range of paragraphs' with the specific action 'Converts existing paragraphs within the specified range into a list.' It distinguishes itself from siblings like 'apply_paragraph_style' or 'insert_text' by focusing on list creation from existing content, not styling or insertion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for usage: 'To create a nested list, use different nesting levels.' However, it does not explicitly state when to use this tool versus alternatives like 'apply_paragraph_style' for non-list formatting or 'insert_text' for adding new list items, nor does it mention prerequisites (e.g., document must exist).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new folder in Google Drive.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name for the new folder | |
| parent_folder_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a creation operation but doesn't mention whether it requires specific permissions, what happens on conflicts (duplicate names), whether folders can be nested, or what the response contains. The description is minimal and lacks important behavioral context for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that gets straight to the point with zero wasted words. It's appropriately sized for a simple creation tool and front-loads the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (which should define the return value), the description doesn't need to explain return values. However, for a mutation tool with no annotations and incomplete parameter documentation, the description should provide more context about permissions, constraints, and behavioral expectations. It's minimally adequate but leaves important gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only 'name' has a description), and the description adds no parameter information beyond what's implied by the tool name. The description doesn't explain 'parent_folder_id' or provide context about folder hierarchy. However, with only 2 parameters and one clearly named ('name'), the baseline is met but not exceeded.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and resource ('new folder in Google Drive'), making the purpose immediately understandable. It doesn't specifically differentiate from sibling tools like 'upload_file_to_drive' or 'create_google_doc', but the resource specificity (folder vs. file/doc) provides some implicit distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'upload_file_to_drive' (for files) or 'create_google_doc' (for documents). There's no mention of prerequisites, permissions needed, or contextual constraints for folder creation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new blank Google Document.
Returns the document ID and web link for the newly created document.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Title for the new Google Document | |
| parent_folder_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the return values (document ID and web link), which is helpful, but lacks critical details: it doesn't specify permissions required (e.g., Google Drive write access), whether creation is immediate or asynchronous, or error conditions (e.g., invalid parent folder). For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence and adds return details in the second. Both sentences earn their place by providing essential information without redundancy or fluff, making it efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 parameters, mutation operation), no annotations, but an output schema (implied by 'Has output schema: true'), the description is reasonably complete. It covers the action and return values, though it lacks behavioral details like permissions or error handling. The output schema likely documents return values, reducing the need for that in the description, but more context on usage would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only 'title' has a description), and the description adds no parameter information beyond what the schema provides. It doesn't explain 'parent_folder_id' (e.g., what it defaults to or its format) or clarify 'title' constraints. With moderate schema coverage, the baseline is 3, as the description doesn't compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a new blank Google Document') and the resource ('Google Document'), distinguishing it from sibling tools like 'create_google_doc_from_markdown' (which creates from markdown) or 'create_folder' (which creates a folder). It specifies 'blank' to indicate no initial content, adding precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'create_google_doc_from_markdown' or 'copy_file', nor does it mention prerequisites (e.g., Google Drive access). It only states what the tool does, without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new Google Document with content imported from markdown.
Uses Google Drive API's native markdown import (July 2024+). Supports standard markdown syntax. Complex formatting is converted using Google's native markdown parser.
Returns the document ID and web link for the newly created document.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Title for the new Google Document | |
| markdown_content | Yes | Markdown content to import into the document | |
| parent_folder_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool creates a new document (implying a write/mutation operation) and mentions the API version and markdown parser behavior, which adds useful context. However, it doesn't cover important behavioral aspects like required permissions, error handling, rate limits, or whether the operation is idempotent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in three sentences: the first states the core purpose, the second provides implementation details, and the third describes the return value. Every sentence adds value without redundancy, and key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (creation with markdown import), no annotations, and the presence of an output schema (which handles return values), the description is reasonably complete. It covers the what, how (API and parser), and output, though it could benefit from more behavioral context like permissions or limitations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (2 out of 3 parameters have descriptions). The description doesn't explicitly discuss parameters, but it implies the purpose of 'markdown_content' and 'title' through context. Since the schema covers most parameters adequately and there are only 3 parameters total, this is above the baseline of 3 for good schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Create a new Google Document with content imported from markdown'), identifies the resource ('Google Document'), and distinguishes it from sibling tools like 'create_google_doc' (which presumably creates empty documents) by specifying the markdown import functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by mentioning 'Google Drive API's native markdown import (July 2024+)' and 'standard markdown syntax,' suggesting this is for markdown-to-Google-Doc conversion. However, it doesn't explicitly state when to use this versus alternatives like 'create_google_doc' or 'upload_file_to_drive,' nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a named range for cross-referencing.
Named ranges allow you to reference specific portions of a document by name instead of by index positions.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document | |
| name | Yes | Name for the range | |
| start_index | Yes | Starting index (inclusive, 1-based) | |
| end_index | Yes | Ending index (exclusive) | |
| tab_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the tool creates named ranges but doesn't disclose behavioral traits like whether this requires specific permissions, if ranges persist across document edits, what happens on duplicate names, or error conditions. The description adds minimal context beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately concise with two sentences that directly explain the tool's purpose and benefit. It's front-loaded with the core action and avoids unnecessary elaboration. However, the second sentence could be more tightly integrated with the first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, 80% schema coverage, and an output schema exists, the description is minimally adequate. It covers the basic purpose but lacks context about when to use it, behavioral implications, or integration with sibling tools. For a creation tool with no annotations, more behavioral disclosure would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, providing a solid baseline. The description doesn't add parameter-specific semantics beyond what the schema already documents (document_id, name, indices, tab_id). It mentions cross-referencing but doesn't clarify parameter relationships or usage examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates named ranges for cross-referencing in documents, specifying the verb 'create' and resource 'named range'. It distinguishes from siblings by focusing on range naming rather than document creation or text manipulation. However, it doesn't explicitly differentiate from 'delete_named_range' or other range-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It mentions the benefit of named ranges (referencing by name instead of index) but doesn't specify scenarios, prerequisites, or when to choose this over other document manipulation tools like 'insert_text' or 'delete_range'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a comment from a document.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document | |
| comment_id | Yes | The ID of the comment to delete |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation 'destructiveHint: true' already indicates this is a destructive operation. The description adds minimal behavioral context beyond confirming deletion, but doesn't specify permissions needed, reversibility, or effects on the document. No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no wasted words. It's front-loaded with the core action and resource, making it highly efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the destructive annotation and output schema, the description is minimally adequate. However, for a destructive tool with many siblings, it lacks context on usage scenarios, permissions, or error handling, leaving gaps in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters clearly documented in the schema. The description doesn't add any semantic details beyond what the schema provides, such as format examples or constraints, meeting the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and target resource ('a comment from a document'), making the purpose unambiguous. However, it doesn't differentiate from sibling tools like 'resolve_comment' or 'delete_range', which could handle similar deletion operations in different contexts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. With siblings like 'resolve_comment' and 'delete_range' available, the description lacks context about appropriate use cases, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a named range.
The named range ID is returned when creating a named range.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document | |
| named_range_id | Yes | ID of the named range to delete |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action is 'Delete', implying a destructive mutation, but fails to mention critical details like required permissions, whether the deletion is permanent or reversible, or any rate limits. This leaves significant gaps in understanding the tool's behavior beyond its basic function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with just two sentences: the first states the core purpose, and the second provides a helpful note about parameter sourcing. Every word earns its place, and the information is front-loaded, making it easy to grasp quickly without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has a simple parameter set (2 required parameters) with full schema coverage and an output schema exists (which handles return values), the description is minimally adequate. However, as a destructive mutation tool with no annotations, it lacks details on permissions, side effects, or error conditions, leaving room for improvement in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the input schema already fully documents both parameters ('document_id' and 'named_range_id'). The description adds minimal value by noting that the 'named_range_id' comes from 'create_named_range', but this is a usage hint rather than semantic clarification. The baseline score of 3 reflects adequate but not enhanced parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and resource ('a named range'), making the purpose immediately understandable. However, it doesn't explicitly differentiate this tool from sibling tools like 'delete_range' or 'delete_comment', which are also deletion operations on different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides minimal guidance by mentioning that the named range ID comes from 'create_named_range', which hints at a prerequisite. However, it offers no explicit advice on when to use this tool versus alternatives (e.g., 'delete_range' for non-named ranges) or any exclusions, leaving usage context largely implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete content within a specified range from a document or tab.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document | |
| start_index | Yes | Starting index of the range (inclusive, 1-based) | |
| end_index | Yes | Ending index of the range (exclusive) | |
| tab_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint=true, indicating this is a destructive operation. The description adds minimal behavioral context beyond this, mentioning the target ('document or tab') but not specifying permissions required, whether deletions are reversible, or how the tool handles errors. It doesn't contradict annotations, but provides only basic supplemental information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded with the core action and target, making it easy to parse. Every part of the sentence contributes meaning, with zero waste or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has a destructive annotation and an output schema (which handles return values), the description is minimally adequate. However, for a destructive operation with 4 parameters, it lacks details about side effects, error conditions, or usage context that would help an agent use it safely and correctly. The presence of an output schema reduces the burden, but more behavioral context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, with clear descriptions for document_id, start_index, and end_index. The description adds no additional parameter semantics beyond what's in the schema, such as explaining tab_id usage or range behavior. With high schema coverage, the baseline score of 3 is appropriate as the description doesn't compensate for the 25% gap but doesn't need to heavily supplement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete content') and target ('within a specified range from a document or tab'), which is specific and unambiguous. It distinguishes itself from other deletion tools like delete_comment or delete_named_range by focusing on content ranges rather than comments or named ranges. However, it doesn't explicitly differentiate from bulk_update_google_doc or replace_all_text which might also modify content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when this tool is appropriate compared to delete_table_column, delete_table_row, or other content modification tools like replace_all_text. There are no prerequisites, exclusions, or comparisons to sibling tools, leaving the agent with minimal context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a column from an existing table.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document | |
| table_start_index | Yes | The index where the table starts | |
| column_index | Yes | The column index (0-based) to delete |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the destructive action ('Delete') but doesn't mention consequences (e.g., data loss, irreversibility), permissions needed, error conditions, or what happens to adjacent columns. This is inadequate for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with zero wasted words. It's front-loaded with the core action and target, making it immediately understandable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation tool with no annotations, the description is minimal but covers the basic action. The existence of an output schema reduces the need to describe return values, but more behavioral context would be beneficial given the tool's complexity and risk.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all three parameters. The description adds no additional parameter information beyond what's in the schema, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and target ('a column from an existing table'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'delete_table_row' or 'delete_range', which would require a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'delete_table_row' or 'delete_range'. The description only states what it does, not when it's appropriate or what prerequisites exist (e.g., table must exist).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a row from an existing table.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document | |
| table_start_index | Yes | The index where the table starts | |
| row_index | Yes | The row index (0-based) to delete |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action is a deletion but lacks critical details: whether this is destructive/permanent, if it requires specific permissions, what happens to adjacent rows, or error conditions. For a mutation tool, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with zero wasted words. It front-loads the core action and resource efficiently, making it easy to parse without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a destructive operation), lack of annotations, and presence of an output schema, the description is minimally adequate. It states what the tool does but omits behavioral context like safety implications or prerequisites. The output schema may cover return values, but the description doesn't address mutation risks or usage constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all three parameters. The description adds no additional parameter semantics beyond implying a table and row context, which is already clear from the schema. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and resource ('a row from an existing table'), making the purpose immediately understandable. It distinguishes itself from sibling tools like 'delete_table_column' by specifying row deletion, though it doesn't explicitly contrast with other deletion tools like 'delete_range' or 'delete_comment'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing table), exclusions, or compare with sibling tools like 'delete_table_column' or 'delete_range', leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find specific text and apply character formatting to it.
This is a convenience tool that combines text search with formatting.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document | |
| text_to_find | Yes | The exact text string to find and format | |
| match_instance | No | Which instance of the text to format (1st, 2nd, etc.) | |
| bold | No | ||
| italic | No | ||
| underline | No | ||
| strikethrough | No | ||
| font_size | No | ||
| font_family | No | ||
| foreground_color | No | ||
| background_color | No | ||
| link_url | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. While it mentions the tool 'combines text search with formatting,' it doesn't address critical behavioral aspects such as whether formatting is additive or replaces existing styles, what happens if text isn't found, permissions required, or rate limits. This leaves significant gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with just two sentences. The first sentence clearly states the purpose, and the second adds useful context about it being a convenience tool. There's no wasted verbiage, and it's front-loaded with the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (12 parameters, mutation operation) and lack of annotations, the description is insufficient. While an output schema exists, the description doesn't address behavioral nuances, parameter interactions, or error conditions. For a tool that modifies documents, more contextual information is needed to ensure safe and correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25%, meaning most parameters lack descriptions in the schema. The tool description doesn't add any parameter-specific information beyond the high-level mention of 'character formatting.' It fails to explain the semantics of parameters like 'match_instance' or formatting options, leaving 10 out of 12 parameters inadequately documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Find specific text and apply character formatting to it.' This specifies both the action (find and apply formatting) and the resource (text). However, it doesn't explicitly differentiate from sibling tools like 'apply_text_style' or 'replace_all_text,' which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some implied usage context by calling it 'a convenience tool that combines text search with formatting,' suggesting it's for efficiency. However, it doesn't explicitly state when to use this tool versus alternatives like 'apply_text_style' or 'replace_all_text,' nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a specific comment with its full thread of replies.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document | |
| comment_id | Yes | The ID of the comment to retrieve |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true, which the description aligns with by using 'Get' (a read operation). The description adds value by specifying that it retrieves 'its full thread of replies,' providing context beyond annotations about the scope of data returned. However, it lacks details on rate limits, authentication needs, or error handling, which would enhance transparency further.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action and resource. It avoids redundancy and wastes no words, making it easy for an agent to parse quickly and understand the tool's function without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (2 parameters, read-only per annotations) and the presence of an output schema (which handles return values), the description is reasonably complete. It specifies the scope ('full thread of replies'), which adds useful context. However, it could improve by mentioning sibling differentiation or usage scenarios to fully guide the agent in a rich toolset environment.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for both parameters (document_id and comment_id). The description doesn't add extra semantic details beyond the schema, such as format examples or interdependencies. Given the high schema coverage, a baseline score of 3 is appropriate, as the schema adequately documents the parameters without needing description supplementation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and resource ('a specific comment with its full thread of replies'), making the purpose evident. However, it doesn't explicitly differentiate from sibling tools like 'list_comments' (which likely lists multiple comments without threads) or 'read_google_doc' (which might retrieve document content), leaving room for improvement in sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention scenarios like needing a single comment's details versus bulk listing, or prerequisites such as having specific IDs, which could help the agent choose appropriately among siblings like 'list_comments' or 'get_document_info'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific Google Document.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true, indicating a safe read operation. The description adds minimal behavioral context by specifying 'detailed information,' but does not disclose aspects like rate limits, authentication needs, or what 'detailed' entails beyond what annotations cover. It does not contradict annotations, so it earns a baseline score for adding some value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that is front-loaded and wastes no words. It efficiently conveys the core purpose without unnecessary elaboration, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, read-only annotation, and an output schema exists), the description is reasonably complete. It states what the tool does, and with annotations and output schema covering safety and return values, it lacks only usage guidelines to be fully adequate for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter 'document_id' fully documented in the schema. The description does not add any meaning beyond the schema, such as format examples or constraints, so it meets the baseline score where the schema handles parameter documentation adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('detailed information about a specific Google Document'), making the purpose understandable. However, it does not explicitly differentiate from sibling tools like 'read_google_doc' or 'list_google_docs', which might have overlapping or similar functions, so it lacks sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With many sibling tools available (e.g., 'read_google_doc', 'list_google_docs', 'search_google_docs'), there is no indication of context, prerequisites, or exclusions for selecting this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the most recently modified Google Documents.
| Name | Required | Description | Default |
|---|---|---|---|
| max_results | No | Maximum number of recent documents to return (1-50) | |
| days_back | No | Only show documents modified within this many days (1-365) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations provide readOnlyHint=true, indicating this is a safe read operation. The description adds value by specifying the scope ('most recently modified'), which is not covered by annotations. However, it does not disclose additional behavioral traits such as rate limits, authentication needs, or pagination behavior. No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence: 'Get the most recently modified Google Documents.' It is front-loaded with the core purpose and contains no unnecessary words or redundancy, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (2 parameters, no nested objects), the presence of annotations (readOnlyHint), and an output schema (which handles return values), the description is reasonably complete. It specifies the scope of retrieval but could benefit from more context on usage versus siblings. Overall, it provides adequate context for a simple read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with clear documentation for both parameters (max_results and days_back). The description does not add any parameter-specific semantics beyond what the schema provides, such as default values or constraints. With high schema coverage, the baseline score of 3 is appropriate as the schema carries the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get the most recently modified Google Documents.' It specifies the verb 'Get' and resource 'Google Documents' with the qualifier 'most recently modified.' However, it does not explicitly differentiate from sibling tools like 'list_google_docs' or 'search_google_docs,' which may offer similar functionality, so it lacks full sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention sibling tools like 'list_google_docs' or 'search_google_docs,' nor does it specify contexts where this tool is preferred or excluded. Usage is implied by the name but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Insert a footnote at the specified index.
Footnotes appear at the bottom of the page and are automatically numbered.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document | |
| index | Yes | Index where to insert footnote (1-based) | |
| footnote_text | Yes | Text content of the footnote |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions automatic numbering and page-bottom placement, which are useful behavioral traits. However, it lacks critical details: whether this is a mutation (implied by 'Insert'), permission requirements, error handling (e.g., invalid index), or output format, leaving significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence, followed by a concise clarification about footnote behavior. Both sentences earn their place by adding value, with no wasted words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters with full schema coverage and an output schema (implied by context signals), the description is minimally adequate. However, as a mutation tool with no annotations, it should provide more behavioral context (e.g., effects, errors) to be fully complete, leaving room for improvement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents parameters (document_id, index, footnote_text). The description adds no additional parameter semantics beyond what the schema provides, such as index constraints or text formatting rules, meeting the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Insert a footnote') and specifies the location ('at the specified index'), with additional context about footnote appearance and numbering. It distinguishes from siblings like 'insert_text' or 'add_comment' by focusing on footnotes, though it doesn't explicitly contrast with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., document must exist), exclusions, or comparisons to sibling tools like 'append_to_google_doc' for general text insertion, leaving usage context implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Insert a horizontal rule (divider line) at the specified index.
Horizontal rules are useful for visually separating sections of content.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document | |
| index | Yes | Index where to insert rule (1-based) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions the tool 'inserts' a horizontal rule, implying a write/mutation operation, but does not disclose behavioral traits like required permissions, whether it modifies document structure, error conditions (e.g., invalid index), or rate limits. This leaves gaps in understanding the tool's behavior beyond basic functionality.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action in the first sentence and uses a second sentence to provide useful context without redundancy. Both sentences earn their place by clarifying purpose and usage, making it efficiently structured and appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (implied by context signals), the description does not need to explain return values. It covers the basic purpose and usage context adequately for a simple insertion tool. However, with no annotations and mutation behavior, it could benefit from more detail on permissions or errors to be fully complete, though it meets minimum requirements.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for both parameters (document_id and index). The description adds minimal value beyond the schema by specifying the index is for insertion but does not provide additional context like valid index ranges or interaction effects. Baseline score of 3 is appropriate as the schema adequately covers parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('insert a horizontal rule'), identifies the resource ('at the specified index'), and distinguishes it from siblings by focusing on a unique formatting element (divider line) not covered by other tools like insert_text or apply_paragraph_style.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implied usage context by stating horizontal rules are 'useful for visually separating sections of content,' which suggests when to use it. However, it does not explicitly mention when not to use it or name alternative tools for similar purposes, such as insert_section_break or apply_paragraph_style for other separation methods.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Insert an image into a Google Document from a resource identifier.
The resource identifier references a blob in the shared blob storage volume (mapped via Docker volumes) that can be accessed by multiple MCP servers.
The image is first uploaded to Google Drive, then inserted into the document.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document | |
| resource_id | Yes | Resource identifier (e.g., 'blob://1733437200-a3f9d8c2b1e4f6a7.png') | |
| index | Yes | The index (1-based) where the image should be inserted | |
| width | No | ||
| height | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the two-step process (upload to Drive then insert), which adds some context about the tool's internal workflow. However, it doesn't cover critical behavioral aspects like required permissions, whether the operation is idempotent, error handling, rate limits, or what happens to the uploaded Drive file. For a mutation tool with zero annotation coverage, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately concise with three sentences that each add value: the core function, resource identifier explanation, and workflow clarification. It's front-loaded with the main purpose. While efficient, the second sentence could be slightly more streamlined, but overall it avoids waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (which reduces need to describe return values) and moderate schema coverage, the description provides adequate basic context about what the tool does. However, for a mutation tool with no annotations and multiple parameters, it should better address behavioral aspects like side effects, permissions, or error conditions to be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 60%, and the description doesn't explicitly mention any parameters. However, it implies the resource_id parameter by describing 'resource identifier' and mentions insertion into a document (relating to document_id and index). The description adds minimal value beyond the schema, which already documents all parameters adequately. With moderate schema coverage, this meets the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('insert an image'), target resource ('Google Document'), and source ('from a resource identifier'). It distinguishes from sibling tools like 'insert_image_from_url' by specifying the resource-based approach and mentions the two-step process (upload to Drive then insert), making the purpose unambiguous and differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'insert_image_from_url' or other image-insertion methods. It mentions the resource identifier references a shared blob storage volume, but doesn't explain when this is preferable or required. No prerequisites, exclusions, or comparative context are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Insert an inline image from a publicly accessible URL.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document | |
| image_url | Yes | Publicly accessible URL to the image | |
| index | Yes | The index (1-based) where the image should be inserted | |
| width | No | ||
| height | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the tool inserts an image, implying a write/mutation operation, but doesn't disclose behavioral traits like required permissions, rate limits, whether the image is embedded or linked, what happens if the URL is invalid, or the response format. The description adds minimal context beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose with zero wasted words. It's appropriately sized for a straightforward tool and front-loads the key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 5 parameters and no annotations, the description is minimal. It covers the basic action but lacks behavioral context, usage guidelines, and detailed parameter semantics. The existence of an output schema helps, but the description doesn't reference it or explain what the tool returns. It's adequate for a simple tool but has clear gaps in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 60%, with 3 of 5 parameters documented. The description adds that the URL must be 'publicly accessible', which provides context for the 'image_url' parameter beyond the schema's basic description. However, it doesn't explain the semantics of 'index' (1-based positioning) or optional 'width'/'height' parameters, leaving gaps in parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('insert'), the resource ('inline image'), and the source ('from a publicly accessible URL'). It distinguishes from sibling tools like 'insert_image_from_resource' by specifying the URL source rather than a resource ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'insert_image_from_resource'. The description mentions the URL must be 'publicly accessible', but this is a parameter constraint rather than usage guidance. There's no mention of prerequisites, error conditions, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Insert a page break at the specified index.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document | |
| index | Yes | The index (1-based) where the page break should be inserted |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('Insert a page break') but does not mention whether this is a destructive operation, requires specific permissions, has side effects (e.g., shifting content), or details about error handling. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with zero waste—it directly states the tool's purpose without unnecessary words. It is appropriately sized and front-loaded, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is an output schema (which handles return values), 100% schema coverage for parameters, and no annotations, the description is minimally adequate. However, as a mutation tool with no behavioral context (e.g., safety, permissions, effects), it lacks completeness for confident agent use, though the structured data mitigates some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters ('document_id' and 'index') fully documented in the input schema. The description adds no additional meaning beyond what the schema provides (e.g., it does not clarify the index format further or explain document_id constraints). Baseline 3 is appropriate when the schema handles parameter documentation effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Insert a page break') and the target ('at the specified index'), with the verb 'insert' being specific and the resource 'page break' distinct from siblings like 'insert_section_break' or 'insert_horizontal_rule'. It precisely defines what the tool does without redundancy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., 'insert_section_break' or 'insert_horizontal_rule' for different document formatting needs). It lacks context about prerequisites, such as requiring an existing document, or exclusions, leaving the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Insert a section break at the specified index.
Section breaks allow different page layouts in different sections of the document.
CONTINUOUS: New section on same page
NEXT_PAGE: New section on next page
EVEN_PAGE: New section on next even page
ODD_PAGE: New section on next odd page
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document | |
| index | Yes | Index where to insert section break (1-based) | |
| section_type | No | Type of section break: 'CONTINUOUS', 'NEXT_PAGE', 'EVEN_PAGE', 'ODD_PAGE' | CONTINUOUS |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It explains what section breaks do and lists the four types, but doesn't disclose important behavioral traits: whether this is a destructive/mutating operation (implied by 'Insert' but not explicit), what permissions are needed, whether there are rate limits, what happens if the index is invalid, or what the output contains. For a mutation tool with zero annotation coverage, this is inadequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly structured and concise. The first sentence states the core purpose, the second explains the concept of section breaks, and the bullet points efficiently list the four types. Every sentence earns its place with zero wasted words, and information is front-loaded appropriately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a mutation tool with no annotations but with a complete input schema (100% coverage) and an output schema exists, the description is minimally adequate. It explains what the tool does and what section breaks are, but doesn't cover behavioral aspects like permissions, side effects, or error conditions. The output schema existence means return values don't need explanation, but other contextual gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters well. The description adds minimal value beyond the schema: it mentions 'specified index' (covered by schema) and lists the four section_type values (also in schema). No additional syntax, format, or constraint information is provided. Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Insert a section break at the specified index' and explains what section breaks do ('allow different page layouts in different sections of the document'). It uses a specific verb ('Insert') and resource ('section break'), but doesn't explicitly differentiate from sibling tools like 'insert_page_break' or 'insert_horizontal_rule'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'insert_page_break' or 'insert_horizontal_rule', nor does it explain when section breaks are preferable to other document formatting options. The only contextual information is the explanation of what section breaks do, which is more about purpose than usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Insert a new table with specified dimensions at a given index.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document | |
| rows | Yes | Number of rows for the new table | |
| columns | Yes | Number of columns for the new table | |
| index | Yes | The index (1-based) where the table should be inserted |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('Insert') but doesn't mention whether this is a write operation (implied), what permissions are required, if it's destructive to existing content, or details about error handling. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action and key parameters without any wasted words. It's appropriately sized for the tool's complexity and gets straight to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 required parameters), 100% schema coverage, and the presence of an output schema (which handles return values), the description is reasonably complete. However, it lacks behavioral context (e.g., permissions, error cases) and usage guidelines, which are notable gaps for a mutation tool with no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions 'specified dimensions' (hinting at rows/columns) and 'at a given index', which aligns with the input schema parameters. Since schema description coverage is 100%, the schema already fully documents all parameters, so the description adds minimal value beyond restating what's in the schema, meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Insert'), resource ('a new table'), and key parameters ('with specified dimensions at a given index'), making the purpose immediately understandable. However, it doesn't explicitly distinguish this tool from sibling tools like 'insert_table_column' or 'insert_table_row', which would require a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'create_google_doc' (for initial document creation) or other table-related tools (e.g., 'insert_table_column'). It lacks context about prerequisites, such as needing an existing document, or exclusions, like not being for modifying existing tables.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Insert a new column into an existing table.
Column indices are 0-based (0 is the first column).
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document | |
| table_start_index | Yes | The index where the table starts | |
| column_index | Yes | The column index (0-based) where to insert | |
| insert_right | No | True to insert right of column, False to insert left |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions column indices are 0-based, which is useful, but fails to cover critical aspects like mutation effects (e.g., whether this modifies the document permanently), error conditions, or response format, leaving significant gaps for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence, followed by a concise clarification about column indices. Both sentences are necessary and add value without any waste, making it efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (mutation of a document table), no annotations, but an output schema exists, the description is minimally adequate. It covers the basic operation but lacks details on behavioral traits and usage context, which are needed for full agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters well. The description adds minimal value by clarifying that 'column_index' is 0-based, but does not provide additional context beyond what the schema specifies, aligning with the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('insert') and resource ('a new column into an existing table'), making the purpose specific and understandable. However, it does not explicitly differentiate from sibling tools like 'insert_table' or 'insert_table_row', which would require a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as 'insert_table' for creating tables or 'delete_table_column' for removal. The description lacks context about prerequisites or scenarios, offering only basic operational details.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Insert a table of contents at the specified index.
The table of contents is auto-generated from document headings (HEADING_1 through HEADING_6). It updates automatically when headings change.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document | |
| index | Yes | Index where to insert TOC (1-based) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions the TOC is 'auto-generated' and 'updates automatically,' which are useful behavioral traits. However, it lacks critical details: whether this is a mutation requiring write permissions, if it overwrites existing content at the index, what happens on errors, or rate limits. For a mutation tool with zero annotation coverage, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded: the first sentence states the core purpose, followed by two sentences adding essential context. Every sentence earns its place by clarifying functionality without redundancy, making it efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 parameters, mutation operation), no annotations, but with an output schema (implied by context signals), the description is reasonably complete. It explains what the tool does and key behaviors, though it could benefit from more detail on permissions or error handling. The output schema likely covers return values, reducing the need for that in the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for 'document_id' and 'index' in the schema. The description adds no additional parameter semantics beyond what the schema provides, such as format examples or constraints. According to rules, with high schema coverage (>80%), the baseline is 3 even without param info in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('insert a table of contents') and resource ('at the specified index'), with additional detail about what the table of contents contains ('auto-generated from document headings HEADING_1 through HEADING_6'). It distinguishes from sibling tools like 'insert_text' or 'insert_image_from_url' by specifying this unique document formatting function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context through 'auto-generated from document headings' and 'updates automatically when headings change,' suggesting it should be used when headings exist and dynamic updates are needed. However, it doesn't explicitly state when to use this tool versus alternatives (e.g., manual TOC creation or other insertion tools) or provide exclusions, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Insert a new row into an existing table.
The table_start_index is the document index where the table begins. Row indices are 0-based (0 is the first row).
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document | |
| table_start_index | Yes | The index where the table starts | |
| row_index | Yes | The row index (0-based) where to insert | |
| insert_below | No | True to insert below the row, False to insert above |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions that 'Row indices are 0-based', which is useful operational context, but fails to describe critical behavioral aspects: whether this is a mutation (implied but not stated), what permissions are required, how it handles errors (e.g., invalid indices), or what the output contains. For a write operation with zero annotation coverage, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately brief (three sentences) and front-loaded with the core purpose. The second sentence clarifies a key parameter, and the third explains indexing, with no redundant information. However, the separation into three short sentences could be slightly more cohesive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (table row insertion), no annotations, but 100% schema coverage and an output schema (implied by context signals), the description is minimally adequate. It covers the basic operation and indexing but lacks behavioral details (e.g., mutation effects, error handling) that would be helpful despite the structured data. The output schema reduces the need to describe return values, but more context on usage and behavior is warranted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all four parameters thoroughly. The description adds minimal value beyond the schema: it repeats 'table_start_index' definition and clarifies row indexing as 0-based (though 'row_index' schema description doesn't specify this). This meets the baseline for high schema coverage but doesn't provide additional semantic context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Insert a new row') and target ('into an existing table'), which is specific and distinguishes it from sibling tools like 'insert_table' or 'delete_table_row'. However, it doesn't explicitly differentiate from other table-related tools beyond the basic verb+resource statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'insert_table' (for creating new tables) or 'delete_table_row'. There's no mention of prerequisites (e.g., table must exist) or contextual usage scenarios, leaving the agent to infer from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Insert text at a specific index within a document or tab.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document | |
| text_to_insert | Yes | The text to insert | |
| index | Yes | The index (1-based) where the text should be inserted | |
| tab_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the tool modifies content ('Insert text'), implying mutation, but doesn't disclose behavioral traits like permission requirements, whether the operation is reversible, how it handles existing text at the index, or rate limits. This leaves significant gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded with the core action and context, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (which covers return values) and moderate schema coverage, the description is minimally adequate. However, as a mutation tool with no annotations, it lacks critical context like side effects, error conditions, or usage examples, leaving room for improvement in guiding safe and effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, with three parameters well-described (document_id, text_to_insert, index) and one (tab_id) lacking description. The description adds no additional parameter semantics beyond what the schema provides, such as explaining index behavior (1-based) or tab_id usage. Baseline 3 is appropriate given the schema does most of the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Insert text') and target ('within a document or tab'), specifying the verb and resource. However, it doesn't differentiate from similar sibling tools like 'append_to_google_doc' or 'replace_all_text', which also modify document text, leaving some ambiguity about when to choose this specific insertion method.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With sibling tools like 'append_to_google_doc' (for adding text at the end) and 'replace_all_text' (for substitution), there's no indication of when precise index-based insertion is preferred, nor any mention of prerequisites or constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all comments in a Google Document.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, indicating a safe read operation. The description adds no behavioral traits beyond this, such as pagination, rate limits, or authentication needs. Since annotations cover the safety profile, a baseline score of 3 is appropriate, as the description does not contradict annotations but adds minimal value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no wasted words, front-loading the core action and resource. It efficiently communicates the purpose without unnecessary detail, earning a perfect score for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (one parameter), high schema coverage, presence of annotations, and an output schema (which handles return values), the description is reasonably complete. However, it lacks usage guidelines for sibling tools, slightly reducing completeness in the broader context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the single parameter 'document_id' fully documented in the schema. The description does not add any meaning beyond the schema, such as format examples or constraints, so it meets the baseline for high schema coverage without compensating value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('all comments in a Google Document'), making the purpose unambiguous. However, it does not differentiate from sibling tools like 'get_comment' (which retrieves a specific comment) or 'reply_to_comment' (which interacts with comments), missing explicit sibling distinction for a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention sibling tools like 'get_comment' for retrieving a single comment or 'resolve_comment' for managing comment states, leaving the agent without context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all tabs in a Google Document, including their hierarchy, IDs, and structure.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document | |
| include_content | No | Whether to include a content summary (character count) for each tab |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds useful context about what information is returned (hierarchy, IDs, structure) and hints at optional content summaries, which goes beyond the annotations. However, it doesn't disclose behavioral traits like rate limits, authentication needs, or pagination behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that efficiently conveys the tool's purpose and key output details. It's front-loaded with the main action and resource, with no redundant or unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 parameters, read-only operation), the description is reasonably complete. It specifies the output includes hierarchy, IDs, and structure, and an output schema exists to detail return values. However, it lacks usage guidelines and some behavioral context (e.g., error conditions), leaving minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents both parameters (document_id and include_content). The description implies the tool operates on a specific document but doesn't add syntax, format details, or examples beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List all tabs'), the resource ('in a Google Document'), and the specific output details ('including their hierarchy, IDs, and structure'). It distinguishes from siblings like 'list_google_docs' (which lists documents) and 'get_document_info' (which provides general document metadata).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a valid document ID), exclusions, or comparisons to similar tools like 'get_document_info' or 'read_google_doc' that might provide overlapping functionality.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the contents of a specific folder in Google Drive.
| Name | Required | Description | Default |
|---|---|---|---|
| folder_id | Yes | ID of the folder to list ('root' for Drive root) | |
| include_subfolders | No | Whether to include subfolders in results | |
| include_files | No | Whether to include files in results | |
| max_results | No | Maximum number of items to return (1-100) |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation provides readOnlyHint=true, which the description doesn't contradict. The description adds minimal behavioral context beyond this - it doesn't mention pagination behavior, rate limits, authentication requirements, or what happens with large folders. However, with the annotation covering the safety aspect, the bar is lower, and the description at least doesn't mislead.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that gets straight to the point with zero wasted words. It's front-loaded with the core functionality and appropriately sized for what it communicates.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that annotations cover the read-only nature and there's an output schema (though not shown), the description provides adequate context for a listing operation. However, with 4 parameters and many sibling listing/search tools, more guidance on usage context would be beneficial for complete agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are documented in the schema. The description doesn't add any parameter-specific information beyond what's in the schema. It mentions 'specific folder' which aligns with folder_id, but provides no additional semantic context about parameter usage or interactions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('contents of a specific folder in Google Drive'), making the purpose immediately understandable. However, it doesn't explicitly distinguish this tool from other listing tools like 'list_google_docs' or 'list_comments', which would require mentioning it's specifically for Drive folder contents rather than documents or comments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With many sibling tools available (like 'list_google_docs', 'search_google_docs', 'get_recent_google_docs'), there's no indication of when folder listing is appropriate versus document listing or searching. No prerequisites or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Google Documents from your Google Drive with optional filtering.
| Name | Required | Description | Default |
|---|---|---|---|
| max_results | No | Maximum number of documents to return (1-100) | |
| query | No | ||
| order_by | No | Sort order: 'name', 'modifiedTime', 'createdTime' | modifiedTime |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds minimal behavioral context beyond this - it mentions 'optional filtering' but doesn't describe pagination behavior, rate limits, authentication requirements, or what happens when no documents match. With annotations covering the safety profile, this earns a baseline score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that gets straight to the point. It's appropriately sized for a listing tool and front-loads the core functionality. There's no wasted verbiage or unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a read-only listing tool with annotations covering safety, an output schema exists (so return values are documented elsewhere), and the schema covers most parameters, the description is reasonably complete. The main gap is the lack of differentiation from similar sibling tools, but otherwise it provides adequate context for the tool's basic function.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (2 of 3 parameters have descriptions), so the schema already documents 'max_results' and 'order_by' well. The description mentions 'optional filtering' which hints at the 'query' parameter but doesn't add meaningful semantics beyond what the schema provides. The baseline 3 is appropriate when the schema does most of the documentation work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and resource ('Google Documents from your Google Drive'), making the purpose immediately understandable. However, it doesn't differentiate this tool from sibling tools like 'get_recent_google_docs' or 'search_google_docs', which appear to serve similar listing/searching functions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'optional filtering' but provides no guidance on when to use this tool versus alternatives like 'get_recent_google_docs' or 'search_google_docs' that appear in the sibling list. There's no indication of prerequisites, typical use cases, or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all permissions on a document.
Shows who has access to the document and their permission levels.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the document |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true, indicating a safe read operation. The description adds value by specifying what information is returned ('who has access' and 'permission levels'), which goes beyond the annotation. However, it does not disclose additional behavioral traits like rate limits or auth requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence and adds clarifying detail in the second. Both sentences earn their place by providing essential information without redundancy, making it efficiently structured and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (one parameter), annotations indicating read-only behavior, and the presence of an output schema, the description is largely complete. It covers the purpose and output semantics adequately, though it could benefit from more explicit usage guidelines to enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter 'document_id' fully documented in the schema. The description does not add meaning beyond the schema, as it does not explain parameter usage or constraints. Baseline score of 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('List all permissions') on a specific resource ('on a document'), distinguishing it from sibling tools like 'remove_permission' or 'update_permission'. It precisely defines what the tool does without being vague or tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing to see document access and permission levels, but does not explicitly state when to use this tool versus alternatives like 'share_document' or provide exclusions. It offers basic context but lacks detailed guidance on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Merge table cells into a single cell.
Creates a merged cell starting at (start_row, start_column) spanning the specified number of rows and columns.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document | |
| table_start_index | Yes | The index where the table starts | |
| start_row | Yes | Starting row index (0-based) | |
| start_column | Yes | Starting column index (0-based) | |
| row_span | Yes | Number of rows to merge | |
| column_span | Yes | Number of columns to merge |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. While it states the tool 'creates a merged cell', it doesn't clarify if this is a destructive operation (overwrites existing content), requires specific permissions, has side effects on document structure, or handles errors (e.g., invalid indices). For a mutation tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and well-structured. The first sentence states the core purpose, and the second elaborates on the parameters without redundancy. Every word earns its place, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, mutation operation) and the presence of an output schema (which reduces the need to describe return values), the description is minimally adequate. However, with no annotations and incomplete behavioral context, it doesn't fully prepare the agent for safe and effective use. It covers the 'what' but lacks the 'how' and 'when'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so all parameters are documented in the schema. The description adds minimal value beyond the schema by mentioning the parameters in context ('starting at (start_row, start_column) spanning the specified number of rows and columns'), but doesn't provide additional syntax, constraints, or examples. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Merge table cells into a single cell.' It specifies the verb ('merge') and resource ('table cells'), making the action unambiguous. However, it doesn't explicitly differentiate from its sibling tool 'unmerge_table_cells' beyond the opposite action, which would have earned a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing table), compare it to sibling tools like 'unmerge_table_cells', or specify scenarios where merging is appropriate versus other table operations. This leaves the agent without contextual usage cues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a file to a different folder in Google Drive.
By default, removes the file from all current parent folders. Set remove_from_current_parents=False to keep the file in multiple locations.
| Name | Required | Description | Default |
|---|---|---|---|
| file_id | Yes | The ID of the file to move | |
| new_parent_folder_id | Yes | The ID of the destination folder | |
| remove_from_current_parents | No | Whether to remove from current parent folders |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the key behavioral trait (default removal from current parents vs. multi-location option), which is valuable. However, it doesn't mention permission requirements, error conditions, rate limits, or what the output contains despite having an output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with two sentences that each earn their place. The first sentence states the core purpose, and the second explains the key behavioral nuance. There's zero waste or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (file movement operation), no annotations, but 100% schema coverage and an output schema, the description is reasonably complete. It explains the core behavior well, though it could benefit from mentioning permission requirements or error scenarios. The output schema means return values don't need explanation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description adds marginal value by clarifying the semantics of remove_from_current_parents (default behavior and alternative), but doesn't provide additional meaning beyond what's in the schema descriptions for file_id and new_parent_folder_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Move a file') and resource ('to a different folder in Google Drive'), distinguishing it from sibling tools like copy_file, trash_file, or permanently_delete_file. It precisely defines the operation without being tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about the default behavior (removing from all current parents) and the alternative behavior (keeping in multiple locations), which helps guide usage. However, it doesn't explicitly mention when to use this tool versus alternatives like copy_file or when moving versus other file operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a file (cannot be recovered).
WARNING: This action cannot be undone. The file will be permanently deleted.
| Name | Required | Description | Default |
|---|---|---|---|
| file_id | Yes | The ID of the file to delete |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint=true, indicating a destructive operation. The description adds valuable context beyond this by emphasizing permanence ('cannot be recovered', 'cannot be undone'), which clarifies the severity beyond just 'destructive'. It doesn't contradict annotations but enriches them with critical behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action in the first sentence, followed by a warning for emphasis. Both sentences earn their place by reinforcing the irreversible nature, with zero wasted words. It's appropriately sized for a high-stakes operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (destructive operation with one parameter), the description is complete. It clearly explains the irreversible behavior, and with annotations covering destructiveness and an output schema present (though not shown), no additional details on return values or side effects are needed. It adequately covers the critical aspects for safe use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with 'file_id' clearly documented. The description doesn't add any parameter-specific information beyond what the schema provides, such as format examples or constraints. With high schema coverage, the baseline score of 3 is appropriate as the description doesn't compensate but doesn't need to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action ('permanently delete') and resource ('a file'), with clear differentiation from sibling tools like 'trash_file' (which likely moves to trash) and 'restore_file' (which recovers). The purpose is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool ('permanently delete a file') and when not to use it ('cannot be recovered', 'WARNING: This action cannot be undone'), distinguishing it from alternatives like 'trash_file' (which is reversible). It clearly indicates this is for irreversible deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the content of a Google Document.
Returns the document content in the specified format. Use 'text' for plain content, 'json' for full structure, or 'markdown' for formatted output.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document (from the URL) | |
| format | No | Output format: 'text' (plain text), 'json' (raw API structure), 'markdown' (experimental) | text |
| max_length | No | ||
| tab_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds useful context about output formats and the experimental nature of 'markdown', but doesn't disclose other behavioral traits like rate limits, authentication needs, or what happens with invalid inputs. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence, followed by essential usage details in two concise sentences. Every sentence earns its place by adding critical information without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has readOnlyHint annotation and an output schema (implied by context signals), the description is reasonably complete for a read operation. It covers the main purpose and output formats, but could improve by addressing parameter nuances like 'tab_id' or error cases, though the output schema likely handles return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, with 'document_id' and 'format' well-described in the schema. The description adds value by explaining the purpose of the 'format' parameter with examples ('text', 'json', 'markdown'), but doesn't clarify 'max_length' or 'tab_id'. Baseline 3 is appropriate as the schema covers half the parameters adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Read the content') and resource ('of a Google Document'), distinguishing it from siblings like 'get_document_info' (metadata) or 'list_google_docs' (listing). It directly addresses what the tool does without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool by specifying it returns document content in various formats, implying it's for extracting content rather than metadata or editing. However, it doesn't explicitly state when not to use it or name alternatives like 'get_document_info' for non-content purposes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a user's access to a document.
The permission ID can be obtained from list_permissions.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the document | |
| permission_id | Yes | The ID of the permission to remove |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. While it indicates a destructive action ('Remove'), it lacks details on permissions required, whether the removal is reversible, error handling (e.g., if the permission doesn't exist), or side effects. This is a significant gap for a mutation 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence, followed by a concise prerequisite note. Both sentences earn their place by providing essential information without redundancy or unnecessary elaboration, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (reducing the need to describe return values) and schema coverage is high, the description is somewhat complete. However, as a destructive tool with no annotations, it should include more behavioral context (e.g., permissions, reversibility) to be fully adequate, leaving clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters ('document_id' and 'permission_id') adequately. The description adds minimal value by noting that the permission ID comes from 'list_permissions,' but does not provide additional syntax, format, or constraints beyond what the schema specifies, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Remove a user's access') and target resource ('to a document'), using a precise verb that distinguishes it from sibling tools like 'share_document' or 'update_permission'. It explicitly identifies what the tool does without being vague or tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool by stating that 'The permission ID can be obtained from list_permissions,' which implies a prerequisite workflow. However, it does not explicitly mention when not to use it or name alternatives (e.g., 'update_permission' for modifying access instead of removing it), which prevents a score of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find and replace all instances of text in the document.
This replaces ALL occurrences of the find text with the replacement text.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document | |
| find_text | Yes | The text to find | |
| replace_text | Yes | The text to replace it with | |
| match_case | No | Whether to match case when finding | |
| tab_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. While it mentions that it replaces 'ALL occurrences' (implying a global operation), it doesn't address critical aspects like whether this is a destructive operation (likely yes), what permissions are required, whether changes are reversible, or any rate limits. For a mutation tool with zero annotation coverage, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded: the first sentence states the core purpose, and the second emphasizes the scope ('ALL occurrences'). There is no wasted language, and every sentence earns its place by reinforcing key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a mutation operation with 5 parameters) and the presence of an output schema (which reduces the need to describe return values), the description is minimally adequate. However, with no annotations and incomplete behavioral context, it leaves gaps in understanding the tool's full impact and usage constraints. It meets basic requirements but lacks depth for safe and effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 80%, so the schema already documents most parameters well (e.g., 'document_id', 'find_text', 'replace_text', 'match_case'). The description adds minimal value beyond the schema—it implies global replacement but doesn't clarify parameter interactions or usage nuances. With high schema coverage, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Find and replace all instances of text in the document.' It specifies the verb ('replace'), resource ('text in the document'), and scope ('ALL occurrences'). However, it doesn't explicitly differentiate from sibling tools like 'format_matching_text' or 'bulk_update_google_doc', which might have overlapping functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'format_matching_text' (which might style rather than replace text) or 'bulk_update_google_doc' (which might handle broader updates). There are no prerequisites, exclusions, or context for usage beyond the basic operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a reply to an existing comment.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document | |
| comment_id | Yes | The ID of the comment to reply to | |
| reply_text | Yes | The content of the reply |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool adds a reply, implying a write/mutation operation, but does not mention permissions required, side effects (e.g., notifications), rate limits, or response format. This leaves significant gaps in understanding the tool's behavior and risks.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It is front-loaded and wastes no space, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (which handles return values) and high schema coverage, the description is minimally adequate. However, as a mutation tool with no annotations, it lacks context on permissions, side effects, and sibling differentiation, leaving room for improvement in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear parameter descriptions in the input schema (e.g., 'The ID of the Google Document'). The description adds no additional meaning beyond the schema, such as format examples or constraints, so it meets the baseline for high schema coverage without compensating value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add a reply') and the target ('to an existing comment'), which is specific and unambiguous. However, it does not differentiate from sibling tools like 'add_comment' or 'resolve_comment', which could lead to confusion about when to use each, preventing a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as 'add_comment' (for new comments) or 'resolve_comment' (for closing comments). It lacks explicit context, prerequisites, or exclusions, leaving usage unclear in relation to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a comment as resolved.
NOTE: Due to Google API limitations, the resolved status may not persist in the Google Docs UI for all document types.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document | |
| comment_id | Yes | The ID of the comment to resolve |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses the core behavior ('Mark a comment as resolved') and a key limitation about persistence due to Google API constraints, adding valuable context beyond basic functionality. However, it lacks details on permissions, error handling, or response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence, followed by a concise NOTE addressing a critical limitation. Both sentences earn their place by providing essential information without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (a mutation with 2 parameters), no annotations, and an output schema (implied by context signals), the description is mostly complete. It covers the action and a key limitation, but could improve by mentioning prerequisites (e.g., authentication) or linking to sibling tools for context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters ('document_id' and 'comment_id'). The description does not add meaning beyond the schema, such as format examples or relationships between parameters, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Mark a comment as resolved') with the resource ('a comment'), distinguishing it from siblings like 'delete_comment', 'get_comment', 'list_comments', and 'reply_to_comment' by focusing on resolution rather than deletion, retrieval, listing, or replying.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing to resolve a comment, but does not explicitly state when to use this tool versus alternatives (e.g., 'delete_comment' for removal or 'reply_to_comment' for engagement). The NOTE provides a limitation but not comparative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restore a file from trash.
The file will be restored to its original location.
| Name | Required | Description | Default |
|---|---|---|---|
| file_id | Yes | The ID of the file to restore |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the file is restored to its original location, which is useful, but fails to mention critical aspects like required permissions, whether the operation is reversible, error conditions (e.g., if the file doesn't exist in trash), or what the output contains. For a mutation tool with zero annotation coverage, this leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with just two sentences that directly state the tool's function and outcome. It is front-loaded with the core purpose and wastes no words, making it highly efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (which handles return values) and high schema coverage for its single parameter, the description covers the basic action adequately. However, as a mutation tool with no annotations, it lacks details on permissions, error handling, and behavioral context, making it incomplete for safe and effective use by an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with the single parameter 'file_id' clearly documented in the schema. The description adds no additional parameter information beyond what the schema provides, such as format examples or constraints. Given the high schema coverage, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Restore') and resource ('a file from trash'), making the purpose immediately understandable. However, it doesn't differentiate this tool from sibling tools like 'trash_file' or 'permanently_delete_file' by explicitly contrasting their functions, which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'permanently_delete_file' or 'trash_file', nor does it mention prerequisites such as the file being in the trash. It only describes what the tool does, not when it should be selected.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for Google Documents by name, content, or other criteria.
| Name | Required | Description | Default |
|---|---|---|---|
| search_query | Yes | Search term to find in document names or content | |
| search_in | No | Where to search: 'name', 'content', or 'both' | both |
| max_results | No | Maximum number of results to return (1-50) | |
| modified_after | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations declare readOnlyHint=true, indicating a safe read operation, which the description does not contradict. However, the description adds minimal behavioral context beyond this, such as search scope ('by name, content, or other criteria') but lacks details on rate limits, authentication needs, or result formatting. With annotations covering safety, it meets a baseline but could be more informative.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose without unnecessary words. It directly states what the tool does, making it easy to parse and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 parameters, 1 required), annotations indicating read-only safety, and the presence of an output schema (which handles return values), the description is reasonably complete. It covers the search purpose and criteria, though it could improve by addressing usage guidelines or behavioral nuances like pagination.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, with three parameters well-described and one ('modified_after') lacking a description. The description mentions search criteria ('by name, content, or other criteria'), which aligns with the schema but does not add significant meaning beyond it, such as explaining search syntax or 'other criteria' specifics. Baseline 3 is appropriate given the schema's coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as searching for Google Documents by name, content, or other criteria, using specific verbs ('search for') and resources ('Google Documents'). However, it does not explicitly differentiate from sibling tools like 'list_google_docs' or 'get_recent_google_docs', which also retrieve documents but with different criteria.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention sibling tools like 'list_google_docs' (for unfiltered listing) or 'get_recent_google_docs' (for time-based retrieval), leaving the agent to infer usage context without explicit direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Star/favorite a file in Google Drive.
Starred files appear in the "Starred" section for easy access.
| Name | Required | Description | Default |
|---|---|---|---|
| file_id | Yes | The ID of the file to star |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions that starred files appear in the 'Starred' section, which is useful context, but doesn't address important behavioral aspects like whether this requires specific permissions, whether it's reversible, or what happens if the file is already starred.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with two sentences that each earn their place. The first states the core action, and the second explains the practical benefit. No wasted words or unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (which handles return values), 100% schema coverage for the single parameter, and relatively simple functionality, the description is reasonably complete. The main gap is the lack of behavioral context that annotations would normally provide.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the single 'file_id' parameter. The description doesn't add any additional parameter semantics beyond what's in the schema, which meets the baseline expectation when schema coverage is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('star/favorite') and resource ('a file in Google Drive'), making the purpose immediately understandable. However, it doesn't explicitly differentiate this tool from its sibling 'unstar_file', which would be needed for a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention the sibling 'unstar_file' tool for removing stars, nor does it explain when starring is appropriate versus other organizational methods like moving to folders.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a file to trash.
The file can be restored using restore_file.
| Name | Required | Description | Default |
|---|---|---|---|
| file_id | Yes | The ID of the file to trash |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the action is reversible via 'restore_file', which is helpful, but fails to disclose critical behavioral traits like whether trashing requires specific permissions, if it affects shared access, what happens to file versions, or if there are rate limits. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and well-structured, consisting of two short sentences that are front-loaded with the primary action. Every sentence earns its place: the first states the core function, and the second adds valuable context about reversibility without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (a single-parameter mutation), 100% schema coverage, and the presence of an output schema (which handles return values), the description is reasonably complete. It covers the basic action and reversibility, though it could improve by addressing behavioral aspects like permissions or side effects, which are not covered by annotations or schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the single parameter 'file_id' clearly documented in the schema. The description adds no additional parameter semantics beyond what the schema provides, such as format examples or constraints. With high schema coverage, the baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't need to given the schema's completeness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Move a file to trash') and identifies the resource ('a file'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'permanently_delete_file' or 'move_file', which would require more specific language about the temporary nature of trashing versus permanent deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by mentioning restoration via 'restore_file', suggesting this is for reversible deletion. However, it lacks explicit guidance on when to use this versus alternatives like 'permanently_delete_file' or 'move_file', and doesn't mention prerequisites such as file permissions or ownership.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unmerge previously merged table cells.
Splits a merged cell back into individual cells.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document | |
| table_start_index | Yes | The index where the table starts | |
| row_index | Yes | Row index (0-based) of the merged cell | |
| column_index | Yes | Column index (0-based) of the merged cell |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers minimal behavioral insight. It states the operation ('unmerge', 'splits back') but doesn't disclose critical traits like whether this is a destructive mutation, what permissions are required, how errors are handled (e.g., if the cell isn't merged), or the effect on table structure. The description is technically accurate but lacks operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences that directly state the action and effect. Every word earns its place, and it's front-loaded with the primary purpose. There's no redundancy or unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (a mutation on table cells), no annotations, and the presence of an output schema (which handles return values), the description is minimally adequate. It states what the tool does but lacks context about prerequisites, side effects, or error conditions. The output schema relieves the description from explaining returns, but more behavioral disclosure would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 4 parameters with clear descriptions. The description adds no parameter-specific semantics beyond implying that parameters identify a merged cell. This meets the baseline of 3 when schema coverage is high, but doesn't provide extra value like explaining coordinate relationships or edge cases.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('unmerge', 'splits back') and resource ('table cells'), making the purpose immediately understandable. It distinguishes from siblings like 'merge_table_cells' by specifying the reverse operation. However, it doesn't explicitly differentiate from other table manipulation tools like 'delete_table_column' or 'update_table_cell_style' beyond the core action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., requires a merged cell to exist), nor does it reference sibling tools like 'merge_table_cells' for context. Usage is implied from the action but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove star from a file in Google Drive.
| Name | Required | Description | Default |
|---|---|---|---|
| file_id | Yes | The ID of the file to unstar |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('Remove star') but does not cover critical aspects like required permissions, whether the operation is reversible, error conditions (e.g., if the file isn't starred), or rate limits. This leaves significant gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste—it directly states the tool's action and target. It is appropriately sized and front-loaded, making it easy to parse without unnecessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, 100% schema coverage, and an output schema exists), the description is minimally adequate. However, as a mutation tool with no annotations, it lacks details on behavioral traits like side effects or error handling, which could be important for completeness in this context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, clearly documenting the 'file_id' parameter. The description adds no additional semantic context beyond implying the parameter's use, so it meets the baseline of 3 where the schema handles the heavy lifting without extra value from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Remove star') and target resource ('a file in Google Drive'), making the purpose specific and understandable. However, it does not explicitly differentiate from sibling tools like 'star_file' beyond the implied opposite action, which slightly limits distinction clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as prerequisites (e.g., the file must already be starred) or comparisons to other tools like 'star_file'. It lacks explicit context or exclusions, offering minimal usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change a permission's role.
The permission ID can be obtained from list_permissions.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the document | |
| permission_id | Yes | The ID of the permission to update | |
| new_role | Yes | New permission role: 'reader', 'writer', or 'commenter' |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It mentions the action ('Change a permission's role') but doesn't cover critical aspects like required permissions, whether the change is reversible, potential side effects, or rate limits. This leaves significant gaps in understanding how the tool behaves in practice.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with just two sentences that directly address the tool's purpose and a key usage note. Every word serves a purpose, and the information is front-loaded, making it easy to grasp quickly without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there's an output schema (not provided in details but indicated as present), the description doesn't need to explain return values. However, for a mutation tool with no annotations, it lacks details on behavioral aspects like error handling or prerequisites beyond the permission ID note. The schema covers parameters well, but the description could do more to address the tool's operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, meaning all parameters are documented in the schema itself (e.g., 'new_role' is described as 'New permission role: 'reader', 'writer', or 'commenter''). The description adds no additional semantic context beyond what's already in the schema, so it meets the baseline but doesn't enhance understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Change a permission's role') and identifies the resource ('permission'), making the purpose immediately understandable. However, it doesn't differentiate this tool from potential siblings like 'share_document' or 'remove_permission' that also deal with permissions, which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some guidance by mentioning that 'The permission ID can be obtained from list_permissions,' which implies a prerequisite relationship. However, it doesn't explicitly state when to use this tool versus alternatives like 'share_document' or 'remove_permission,' nor does it specify any exclusions or contextual constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Style a table cell (background, padding, borders).
Cell positions are 0-based. Provide at least one style property.
| Name | Required | Description | Default |
|---|---|---|---|
| document_id | Yes | The ID of the Google Document | |
| table_start_index | Yes | The index where the table starts | |
| row_index | Yes | Row index (0-based) | |
| column_index | Yes | Column index (0-based) | |
| background_color | No | ||
| padding_top | No | ||
| padding_bottom | No | ||
| padding_left | No | ||
| padding_right | No | ||
| border_top_color | No | ||
| border_top_width | No | ||
| border_bottom_color | No | ||
| border_bottom_width | No | ||
| border_left_color | No | ||
| border_left_width | No | ||
| border_right_color | No | ||
| border_right_width | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the 0-based indexing constraint and requirement for at least one style property, which are useful. However, it doesn't disclose that this is a mutation operation (updates document), potential side effects, permission requirements, rate limits, or what happens when invalid styles are provided. For a tool with 17 parameters and no annotations, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with only two sentences, both of which provide essential information. The first sentence states the purpose and scope, the second provides critical constraints. There is zero wasted language, and the most important information (what the tool does) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (17 parameters, mutation operation) and the presence of an output schema (which means return values are documented elsewhere), the description provides basic but incomplete context. It covers the core purpose and some constraints but lacks important behavioral details like mutation effects, error conditions, and permission requirements. The existence of an output schema helps, but for a mutation tool with many parameters, more guidance would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 24%, so the description needs to compensate. It mentions 'Cell positions are 0-based' which clarifies the row_index and column_index parameters, and 'Provide at least one style property' which implies at least one of the style parameters must be non-null. However, it doesn't explain the meaning of table_start_index, document_id, or the various style parameters beyond naming them. The description adds some value but doesn't fully compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Style') and target ('table cell') with specific style properties mentioned (background, padding, borders). It distinguishes from siblings like apply_paragraph_style and apply_text_style by focusing on table cells. However, it doesn't explicitly differentiate from bulk_update_google_doc which might also handle styling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some usage context by specifying 'Cell positions are 0-based' and 'Provide at least one style property', which are important constraints. However, it doesn't explicitly state when to use this vs. alternatives like bulk_update_google_doc or other styling tools, nor does it mention prerequisites like document access permissions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload a file to Google Drive from base64-encoded data.
Accepts file data in base64 format and uploads it to Google Drive. Supports any file type. Returns the file ID and web link.
| Name | Required | Description | Default |
|---|---|---|---|
| file_data | Yes | Base64-encoded file data | |
| name | Yes | Name for the file in Drive | |
| mime_type | Yes | MIME type of the file (e.g., 'application/pdf', 'text/plain') | |
| parent_folder_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers minimal behavioral insight. It mentions 'Supports any file type' and return values, but lacks critical details like authentication requirements, rate limits, error handling, or whether the upload is synchronous/asynchronous. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding operational behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in three brief sentences that cover core functionality, format support, and return values. There's no wasted text, though it could be slightly more front-loaded with key distinctions from sibling tools.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (which handles return value documentation) and moderate schema coverage, the description provides basic context but is incomplete for a mutation tool. It lacks permission requirements, error conditions, and differentiation from similar upload tools, making it minimally adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, providing good baseline documentation for parameters. The description adds marginal value by explicitly mentioning 'base64-encoded data' (already in schema) and implying file type support, but doesn't clarify parameter interactions or provide examples beyond what the schema describes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Upload a file to Google Drive') and resource ('from base64-encoded data'), making the purpose immediately understandable. It distinguishes itself from sibling tools like 'upload_file_to_drive_from_resource' by specifying the base64 source, though it doesn't explicitly contrast with all similar tools like 'upload_image_to_drive'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. The description doesn't mention when to choose this over sibling tools like 'upload_file_to_drive_from_resource' or 'upload_image_to_drive', nor does it specify prerequisites or constraints for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload a file to Google Drive from a resource identifier.
The resource identifier references a blob in the shared blob storage volume (mapped via Docker volumes) that can be accessed by multiple MCP servers.
This allows other MCP servers to upload resources to the blob storage, and this server can then upload those resources to Google Drive without needing to transfer the actual file data through the MCP protocol.
Supports any file type. Returns the file ID and web link.
| Name | Required | Description | Default |
|---|---|---|---|
| resource_id | Yes | Resource identifier (e.g., 'blob://1733437200-a3f9d8c2b1e4f6a7.pdf') | |
| name | No | ||
| parent_folder_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does well by explaining the blob storage mechanism and multi-server access pattern, and mentions support for any file type and return values. However, it doesn't address important behavioral aspects like authentication requirements, rate limits, error conditions, or whether this is a destructive operation (though 'upload' implies creation).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with four sentences that each add value: 1) core purpose, 2) resource identifier explanation, 3) multi-server workflow benefit, 4) file type support and return values. No wasted words, front-loaded with the most important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (upload operation with blob storage integration), no annotations, and an output schema (which handles return value documentation), the description provides good contextual completeness. It explains the unique blob storage mechanism and multi-server workflow that aren't evident from the schema alone. The main gap is lack of behavioral details like permissions or error handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only 'resource_id' has a description), but the description compensates well by explaining what 'resource_id' represents (blob storage references) and the overall purpose. It doesn't detail the semantics of 'name' or 'parent_folder_id' parameters, but provides enough context about the upload operation to make the tool usable. With 3 parameters and low schema coverage, this is above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Upload a file'), target resource ('to Google Drive'), and source ('from a resource identifier'). It distinguishes itself from sibling tools like 'upload_file_to_drive' and 'upload_image_to_drive_from_resource' by specifying it works with any file type from blob storage, not just images or direct uploads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about when to use this tool: when you have a resource identifier referencing blob storage accessible by multiple MCP servers, and you want to upload that resource to Google Drive without transferring file data through MCP. However, it doesn't explicitly state when NOT to use it or name specific alternatives like 'upload_file_to_drive' for direct uploads.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload an image to Google Drive.
Accepts an image as ImageContent (base64-encoded data with MIME type) and uploads it to Google Drive. Returns the file ID and web link for the uploaded image.
| Name | Required | Description | Default |
|---|---|---|---|
| image | Yes | Image content to upload to Google Drive | |
| name | Yes | Name for the image file in Drive (e.g., 'photo.png') | |
| parent_folder_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions the tool 'uploads' (implying a write operation) and returns file ID and web link, but lacks critical behavioral details: required permissions, rate limits, file size constraints, error handling, or whether it overwrites existing files. For a mutation tool with zero annotation coverage, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: three sentences that cover purpose, input, and output without redundancy. However, the second sentence could be more front-loaded by merging with the first, and it lacks critical behavioral details that would justify additional length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (mutation with 3 parameters), no annotations, and an output schema (which covers return values), the description is incomplete. It misses essential context: authentication requirements, error cases (e.g., invalid MIME types), sibling tool differentiation, and usage prerequisites. The output schema helps, but the description should compensate for missing annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (2 of 3 parameters have descriptions). The description adds minimal value beyond the schema: it clarifies that 'image' is 'base64-encoded data with MIME type' (schema already references ImageContent with mimeType) and mentions returns (covered by output schema). It doesn't explain 'parent_folder_id' behavior (e.g., default location if null) or 'name' constraints (e.g., uniqueness). Baseline 3 is appropriate given moderate schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Upload an image to Google Drive' specifies the verb (upload) and resource (image to Google Drive). However, it doesn't explicitly differentiate from sibling tools like 'upload_file_to_drive' or 'upload_image_to_drive_from_resource', which handle similar functions with different input sources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'upload_file_to_drive' (for general files) or 'upload_image_to_drive_from_resource' (for images from resources), leaving the agent to infer usage based on parameter names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload an image to Google Drive from a resource identifier.
The resource identifier references a blob in the shared blob storage volume (mapped via Docker volumes) that can be accessed by multiple MCP servers.
This allows other MCP servers to upload resources to the blob storage, and this server can then upload those resources to Google Drive without needing to transfer the actual file data through the MCP protocol.
Returns the file ID and web link for the uploaded image.
| Name | Required | Description | Default |
|---|---|---|---|
| resource_id | Yes | Resource identifier (e.g., 'blob://1733437200-a3f9d8c2b1e4f6a7.png') | |
| name | No | ||
| parent_folder_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the resource identifier system and the return values (file ID and web link), which is helpful. However, it doesn't mention important behavioral aspects like authentication requirements, rate limits, error conditions, file size limits, or whether this is a mutating operation (though 'upload' implies creation).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly structured: a clear purpose statement followed by explanatory context about the resource system, then the return values. Every sentence earns its place by adding valuable information not obvious from the tool name or schema. No wasted words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a mutating tool with no annotations, 3 parameters, and an output schema (which handles return value documentation), the description does quite well. It explains the resource system architecture and return values. The main gap is lack of behavioral warnings (permissions, limits, errors) that would be important for a write operation, but the output schema reduces the burden somewhat.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 33% schema description coverage (only 'resource_id' has a description), the description compensates well by explaining what a resource identifier is ('references a blob in the shared blob storage volume') and the architectural context. While it doesn't detail the 'name' and 'parent_folder_id' parameters, it provides essential context about the resource system that the schema alone doesn't capture.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('upload an image'), target resource ('to Google Drive'), and source ('from a resource identifier'). It distinguishes this tool from siblings like 'upload_image_to_drive' (which likely uploads from a different source) and 'upload_file_to_drive_from_resource' (which handles generic files rather than specifically images).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about when to use this tool: when you have a resource identifier referencing a blob in shared storage and want to upload that image to Google Drive. It explains the architectural benefit (avoiding data transfer through MCP). However, it doesn't explicitly state when NOT to use it or name specific alternatives among the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools have distinct purposes, but there is notable overlap in some areas. For example, apply_text_style and format_matching_text both handle character formatting, and multiple tools like insert_image_from_resource and upload_image_to_drive_from_resource share similar functionality with slight variations. The descriptions help differentiate them, but an agent might struggle to choose between overlapping tools.
Tool names largely follow a consistent verb_noun pattern, such as create_google_doc, delete_comment, and insert_table. There are minor deviations like bulk_update_google_doc and get_recent_google_docs, but overall the naming is predictable and readable across the set.
With 57 tools, the count is excessive for a Google Docs server, making it feel heavy and potentially overwhelming. While the domain is broad, many tools could be consolidated or omitted without losing functionality, indicating poor scoping and an overly granular approach.
The tool set provides comprehensive coverage for Google Docs and Drive operations, including full CRUD for documents, comments, tables, and permissions, along with advanced features like markdown import, batch updates, and resource handling. There are no obvious gaps, and agents can handle complete workflows without dead ends.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Create and manage documents, spreadsheets, and presentations from your AI assistant.
Connect AI assistants to Google Sheets through controlled tools for reading and updating rows.
Persistent docs and memory for AI agents — read, write, organize & search a shared workspace.
Provides tools for searching Google Workspace documentation and much more.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/nickweedon/google-docs-mcp-docker'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
