Google Big Query

execute_sql

Destructive

Run a SQL query in the project and return the result. Prefer the execute_sql_readonly tool if possible.

This tool can execute any query that bigquery supports including:

SQL Queries (SELECT, INSERT, UPDATE, DELETE, CREATE, etc.)
AI/ML functions like AI.FORECAST, ML.EVALUATE, ML.PREDICT
Any other query that bigquery supports.

Example Queries:

-- Insert data into a table.
INSERT INTO `my_project.my_dataset`.my_table (name, age)
VALUES ('Alice', 30);

-- Create a table.
CREATE TABLE `my_project.my_dataset`.my_table (
  name STRING,
  age INT64);

-- DELETE data from a table.
DELETE FROM `my_project.my_dataset`.my_table WHERE name = 'Alice';

-- Create Dataset
CREATE SCHEMA `my_project.my_dataset` OPTIONS (location = 'US');

-- Drop table
DROP TABLE `my_project.my_dataset`.my_table;

-- Drop dataset
DROP SCHEMA `my_project.my_dataset`;

-- Create Model
CREATE OR REPLACE MODEL `my_project.my_dataset.my_model`
OPTIONS (
  model_type = 'LINEAR_REG'
  LS_INIT_LEARN_RATE=0.15,
  L1_REG=1,
  MAX_ITERATIONS=5,
  DATA_SPLIT_METHOD='SEQ',
  DATA_SPLIT_EVAL_FRACTION=0.3,
  DATA_SPLIT_COL='timestamp') AS
SELECT col1, col2, timestamp, label FROM `my_project.my_dataset.my_table`;

Queries executed using the execute_sql tool will always have the default job label goog-mcp-server: true automatically set in addition to any custom labels provided in the request. Queries are charged to the project specified in the project_id field.

Input Schema

TableJSON Schema

Name	Required	Description
`query`	Yes	Required. The query to execute in the form of a GoogleSQL query.
`dryRun`	No	Optional. If set to true, BigQuery doesn't run the job. Instead, if the query is valid, BigQuery returns statistics about the job such as how many bytes would be processed. If the query is invalid, an error returns. The default value is false.
`labels`	No	Optional. The labels associated with this query. Labels can be used to organize and group query jobs. Label keys and values can be no longer than 63 characters, can only contain lowercase letters, numeric characters, underscores and dashes. International characters are allowed. Label keys must start with a letter and each label in the map must have a different key.
`projectId`	Yes	Required. Project that will be used for query execution and billing.

Output Schema

TableJSON Schema

Name	Required	Description
`rows`	No	An object with as many results as can be contained within the maximum permitted reply size. To get any additional rows, you can call GetQueryResults and specify the jobReference returned above.
`errors`	No	Output only. The first errors or warnings encountered during the running of the job. The final message includes the number of errors that caused the process to stop. Errors here do not necessarily mean that the job has completed or was unsuccessful. For more information about error messages, see [Error messages](https://cloud.google.com/bigquery/docs/error-messages).
`schema`	No	The schema of the results. Present only when the query completes successfully.
`queryId`	No	Output only. The ID of the query.
`jobComplete`	No	Whether the query has completed or not. If rows or totalRows are present, this will always be true. If this is false, totalRows will not be available.
`totalSlotMs`	No	Output only. Number of slot ms the user is actually billed for.
`totalBytesBilled`	No	Output only. The total number of bytes billed for the query. Only applies if the project is configured to use on-demand pricing.
`numDmlAffectedRows`	No	Output only. The number of rows affected by a DML statement.
`totalBytesProcessed`	No	Output only. The total number of bytes processed for this query.

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the unsafe nature is covered. The description adds useful behavioral context by disclosing the default job label and that queries are billed to the specified project. This goes beyond the annotations without contradicting them.

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

Conciseness4/5

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

The description is front-loaded with the core purpose and the read-only alternative. The extensive example block is somewhat verbose but earns its place by illustrating the wide range of BigQuery SQL operations, including DDL, DML, and AI/ML functions.

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

Completeness4/5

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

For a tool with rich annotations and a full output schema, the description provides sufficient context: what it does, when to prefer the alternative, supported query types, billing behavior, and label handling. Minor gaps like query timeout behavior are adequately covered by the output schema and the already complete parameter documentation.

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

Parameters3/5

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

Schema description coverage is 100%, so all parameters are already documented in the schema. The description reinforces that projectId controls billing and demonstrates query syntax through examples, but it does not add significant new parameter-level meaning beyond the schema.

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

Purpose5/5

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

The description states a clear verb and resource: run a SQL query and return the result. It also explicitly distinguishes itself from the sibling execute_sql_readonly by saying users should prefer the read-only tool when possible. The examples further clarify the full range of SQL operations supported.

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

Usage Guidelines5/5

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

The description gives explicit guidance to prefer execute_sql_readonly when possible, which tells an agent when not to use this tool. The mutation examples (INSERT, UPDATE, DELETE, CREATE, DROP) make it clear this tool is intended for cases where read-only execution is insufficient.

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

All Google Big Query tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.2/5.0

Disambiguation5/5

Each tool has a distinct purpose: execute_sql and execute_sql_readonly are clearly separated by write/read access, while get_dataset_info, get_table_info, list_dataset_ids, and list_table_ids cover distinct metadata retrieval operations. No overlap in functionality.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern: execute_sql, get_dataset_info, get_table_info, list_dataset_ids, list_table_ids. The verb clearly indicates the action (execute, get, list) and the noun indicates the target resource.

Tool Count5/5

With 6 tools, the set is well-scoped for a BigQuery server. It provides both query execution and metadata listing/inspection without unnecessary duplication or bloat.

Completeness5/5

The tool set covers both data manipulation and metadata discovery. The execute_sql tool supports all BigQuery SQL (SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, etc.), allowing full lifecycle management. Metadata tools provide listing and detailed info for datasets and tables, covering the core introspection needs.

Resources

Need Help?