Google Big Query

Server Details

The BigQuery remote MCP server is a fully managed service that uses the Model Context Protocol to connect AI applications and LLMs to BigQuery data sources. It provides secure, standardized tools for AI agents to list datasets and tables, retrieve schemas, generate and execute SQL queries through natural language, and analyze data—enabling direct access to enterprise analytics data without requiring manual SQL coding.

If you are the author of this connector, you can claim ownership by verifying the domain or GitHub account it belongs to. Claimed connector authors can inspect health checks, view analytics, and manage their listing.

Status: Healthy
Uptime: 99.9% over 59 days
Last Tested: 2026-10-15 12:43
Transport: Streamable HTTP · MCP 2025-11-25
URL

TDQS

A4.1/5.0

Scored 2026-10-05 07:20 across 9 tools

Disambiguation4/5

The execute_sql / execute_sql_readonly pair has overlapping purpose but descriptions clearly delineate when to prefer readonly. get_job (status/config) and get_query_results (row retrieval/pagination) are also adjacent but their roles are spelled out well enough to distinguish.

Naming Consistency5/5

Every tool follows a clean verb_noun snake_case pattern (cancel_job, execute_sql, get_dataset_info, list_table_ids). The readonly suffix on execute_sql_readonly is the only minor deviation and remains highly readable.

Tool Count5/5

Nine tools is well-scoped for a query-centric BigQuery server, covering execution, job lifecycle, and metadata listing without redundancy.

Completeness4/5

The surface covers query execution, job polling/cancellation, and dataset/table metadata discovery; DDL via execute_sql handles create/drop. Minor gaps exist (no dedicated schema/column inspection or result export), but core workflows have no dead ends.

Available Tools

9 tools

cancel_job

DestructiveIdempotent

Inspect

Cancel a running BigQuery job.

Use this tool to cancel a query job that is currently executing (i.e. returned job_complete: false with a job_id from execute_sql or execute_sql_readonly). Specify the job_id to abort.

ParametersJSON Schema

Name	Required	Description
`jobId`	Yes	Required. Job ID of the job to cancel.
`location`	Yes	Required. The geographic location of the job.
`projectId`	Yes	Required. Project ID of the job to cancel.

Output Schema

ParametersJSON Schema

Name	Required	Description
`job`	No	The final state of the job.
`kind`	No	The resource type of the response.

execute_sqlA

Destructive

Inspect

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, AI.KEY_DRIVERS, 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.

Query Execution Behavior:

If the query completes within the synchronous timeout (default 20 seconds or custom timeout_ms), the tool returns job_complete: true and the initial result rows directly. For fast queries, job_id may be omitted as no persistent background job is created; no further action or polling is needed.
If the query takes longer than timeout_ms, the tool returns job_complete: false and a job_id. In this case, use the get_query_results tool with job_id to poll until job_complete: true, or use cancel_job to abort the running query.
You can optionally specify timeout_ms to configure the maximum synchronous wait time in milliseconds (defaults to 20,000 ms), and job_timeout_ms to enforce a hard server-side timeout after which BigQuery automatically terminates the job.

ParametersJSON 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.
`timeoutMs`	No	Optional. Optional: Specifies the maximum amount of time, in milliseconds, that the client is willing to wait for the query to complete. By default, this limit is 20 seconds (20,000 milliseconds).
`jobTimeoutMs`	No	Optional. Optional: Job timeout in milliseconds. If this time limit is exceeded, BigQuery will attempt to stop the query job.

Output Schema

ParametersJSON 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.
`jobId`	No	Output only. The ID of the BigQuery job created for this query, if any. Present when a query job is created (e.g. for long-running operations, DML, scripts). Use this ID with `get_query_results`, `cancel_job`, or `get_job`.
`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.8/5.0

Behavior5/5

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

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description details the execution model: synchronous timeout, job_complete flag, job_id behavior, and the optional timeout_ms and job_timeout_ms controls. It also discloses the automatic job label and billing implications. This goes well beyond what annotations provide and is technically accurate.

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 long but well-organized into sections (intro, examples, execution behavior). The essential statement and sibling preference are front-loaded. The extensive SQL examples are relevant for a tool that accepts arbitrary SQL, and the timeout explanations are necessary. While it could be tightened (e.g., trimming some repetitive phrasing like 'Optional' in parameter descriptions), the structure makes it scannable and each section earns its place.

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

Completeness5/5

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

Given the tool's complexity (6 params, output schema present, destructive annotations), the description is thorough. It covers usage, alternatives, async behavior, polling, cancellation, billing, and even provides usage examples. The output schema exists, so return values are externally documented. Nothing an agent needs to decide whether to call this tool or to do so correctly is missing.

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

Parameters4/5

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

The schema itself documents all six parameters with 100% coverage, so the baseline is 3. However, the description adds practical context: it explains the consequences of timeout_ms versus job_timeout_ms, describes the labels format and bigquery charging model, and gives a concrete example of labels usage. This exceeds schema documentation by clarifying real-world impact, earning a 4.

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 opens with a specific verb and resource: 'Run a SQL query in the project and return the result.' It then enumerates the full range of supported queries (SELECT, INSERT, UPDATE, DELETE, CREATE, AI/ML functions) and explicitly contrasts itself with the sibling execute_sql_readonly by saying 'Prefer the execute_sql_readonly tool if possible.' This makes its role and scope unmistakable.

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 explicitly recommends using execute_sql_readonly when possible, giving clear criteria for selecting the safer alternative. It also explains the async behavior, directing agents to use get_query_results for polling and cancel_job for aborting long-running queries. It further clarifies billing and the default label, answering when and why to use this tool versus others.

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

execute_sql_readonlyA

Read-onlyIdempotent

Inspect

Run a read-only SQL query in the project and return the result. Prefer this tool over execute_sql if possible.

This tool is restricted to only SELECT statements. INSERT, UPDATE, and DELETE statements and stored procedures aren't allowed. If the query doesn't include a SELECT statement, an error is returned. For information on creating queries, see the GoogleSQL documentation.

IMPORTANT: For predictive and analytical tasks (forecasting, anomaly detection, key driver / root cause analysis, classification, churn prediction, or text generation), ALWAYS execute computation in-warehouse using BigQuery native AI/ML functions (AI.FORECAST, AI.DETECT_ANOMALIES, AI.KEY_DRIVERS, AI.CLASSIFY, AI.GENERATE) rather than exporting raw rows to a local Python sandbox. In-warehouse execution scales to billions of rows, preserves governance, and eliminates data egress latency.

Example Queries:

-- Count the number of penguins in each island.
SELECT island, COUNT(*) AS population
FROM bigquery-public-data.ml_datasets.penguins GROUP BY island

-- Forecast data using AI.FORECAST
SELECT *
FROM AI.FORECAST(TABLE `project.dataset.my_table`, data_col => 'num_trips',
  timestamp_col => 'date', id_cols => ['usertype'], horizon => 30)

-- Detect anomalies in time series data using AI.DETECT_ANOMALIES
SELECT *
FROM AI.DETECT_ANOMALIES(
  TABLE `project.dataset.historical_metrics`,
  TABLE `project.dataset.recent_metrics`,
  data_col => 'num_requests',
  timestamp_col => 'timestamp'
)

-- Identify key drivers of metric changes using AI.KEY_DRIVERS
SELECT *
FROM AI.KEY_DRIVERS(
  TABLE `project.dataset.sales_summary`,
  metric_col => 'total_revenue',
  dimension_cols => ['region', 'product_category'],
  interest_label_col => 'is_current_quarter'
)

-- Classify text into categories using AI.CLASSIFY
SELECT
  ticket_id,
  AI.CLASSIFY(ticket_text, ['Billing', 'Technical Support', 'Feature Request']) AS category
FROM `project.dataset.support_tickets`

-- Generate text or summaries using AI.GENERATE
SELECT
  review_id,
  AI.GENERATE(CONCAT('Summarize this customer review: ', review_text)).result AS summary
FROM `project.dataset.reviews`

Queries executed using the execute_sql_readonly tool will always have the 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.

Query Execution Behavior:

If the query completes within the synchronous timeout (default 20 seconds or custom timeout_ms), the tool returns job_complete: true and the result rows directly. For fast queries, job_id may be omitted as no persistent background job is created; no further action or polling is needed.
If the query takes longer than timeout_ms, the tool returns job_complete: false and a job_id. In this case, use the get_query_results tool with job_id to poll until job_complete: true, or use cancel_job to abort the running query.
You can optionally specify timeout_ms to configure the maximum synchronous wait time in milliseconds (defaults to 20,000 ms), and job_timeout_ms to enforce a hard server-side timeout after which BigQuery automatically terminates the job.

ParametersJSON 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.
`timeoutMs`	No	Optional. Optional: Specifies the maximum amount of time, in milliseconds, that the client is willing to wait for the query to complete. By default, this limit is 20 seconds (20,000 milliseconds).
`jobTimeoutMs`	No	Optional. Optional: Job timeout in milliseconds. If this time limit is exceeded, BigQuery will attempt to stop the query job.

Output Schema

ParametersJSON 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.
`jobId`	No	Output only. The ID of the BigQuery job created for this query, if any. Present when a query job is created (e.g. for long-running operations, DML, scripts). Use this ID with `get_query_results`, `cancel_job`, or `get_job`.
`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.7/5.0

Behavior5/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description is fully consistent with them. Beyond that, the description adds substantial behavioral context: automatic job label injection, billing to the projectId, synchronous timeout semantics with job_complete true/false, job_id being omitted for fast queries, and the interplay between timeout_ms and job_timeout_ms. This is exactly the kind of runtime behavior an agent cannot infer from annotations or schema.

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

Conciseness3/5

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

The content is well-structured and front-loaded: purpose, sibling preference, and the SELECT-only restriction come first. However, the description is considerably overlong, dominated by seven SQL examples and a large AI/ML directive block that go beyond the core tool contract. Every sentence does not earn its place; the example section could be trimmed to one representative query.

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

Completeness5/5

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

For a complex tool with 6 parameters, an output schema, and asynchronous execution paths, this description is exceptionally complete. It covers the SELECT-only restriction and error behavior, the sync/async contract with job_complete and job_id, follow-up tool routing, timeout configuration, billing, and labels. The output schema already covers return values, so nothing material is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3. The description nevertheless adds value beyond the schema: it clarifies that queries are charged to the project specified in projectId, that the goog-mcp-server label is automatically added on top of custom labels, and it explains the behavioral consequence of timeoutMs (returns job_complete=false with a job_id) versus jobTimeoutMs (hard server-side termination). This materially helps an agent choose parameter values.

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 first sentence states a specific verb and resource: 'Run a read-only SQL query in the project and return the result.' It immediately distinguishes itself from the sibling execute_sql by name, and the SELECT-only restriction further sharpens the scope. An agent can tell exactly what this tool does without opening the schema.

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?

'Prefer this tool over execute_sql if possible' is an explicit routing directive naming the exact alternative. The SELECT-only constraint explains when this tool cannot be used (writes), and the Query Execution Behavior section explicitly directs the agent to get_query_results for polling and cancel_job for aborting long-running jobs. No usage ambiguity remains.

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

get_dataset_infoA

Read-onlyIdempotent

Inspect

Get metadata information about a BigQuery dataset or BigLake namespace.

ParametersJSON Schema

Name	Required	Description	Default
`datasetId`	Yes	Required. Dataset ID of the dataset request.
`projectId`	Yes	Required. Project ID of the dataset request.

Output Schema

ParametersJSON Schema

Name	Required	Description
`id`	No	Output only. The fully-qualified unique name of the dataset in the format projectId:datasetId. The dataset name without the project name is given in the datasetId field. When creating a new dataset, leave this field blank, and instead specify the datasetId field.
`etag`	No	Output only. A hash of the resource.
`kind`	No	Output only. The resource type.
`tags`	No	Output only. Tags for the dataset. To provide tags as inputs, use the `resourceTags` field.
`type`	No	Output only. Same as `type` in `ListFormatDataset`. The type of the dataset, one of: * DEFAULT - only accessible by owner and authorized accounts, * PUBLIC - accessible by everyone, * LINKED - linked dataset, * EXTERNAL - dataset with definition in external metadata catalog, * BIGLAKE_ICEBERG - a Biglake dataset accessible through the Iceberg API, * BIGLAKE_HIVE - a Biglake dataset accessible through the Hive API.
`access`	No	Optional. An array of objects that define dataset access for one or more entities. You can set this property when inserting or updating a dataset in order to control who is allowed to access the data. If unspecified at dataset creation time, BigQuery adds default dataset access for the following entities: access.specialGroup: projectReaders; access.role: READER; access.specialGroup: projectWriters; access.role: WRITER; access.specialGroup: projectOwners; access.role: OWNER; access.userByEmail: [dataset creator email]; access.role: OWNER; If you patch a dataset, then this field is overwritten by the patched dataset's access field. To add entities, you must supply the entire existing access array in addition to any new entities that you want to add.
`labels`	No	The labels associated with this dataset. You can use these to organize and group your datasets. You can set this property when inserting or updating a dataset. See [Creating and Updating Dataset Labels](https://cloud.google.com/bigquery/docs/creating-managing-labels#creating_and_updating_dataset_labels) for more information.
`location`	No	The geographic location where the dataset should reside. See https://cloud.google.com/bigquery/docs/locations for supported locations.
`selfLink`	No	Output only. A URL that can be used to access the resource again. You can use this URL in Get or Update requests to the resource.
`description`	No	Optional. A user-friendly description of the dataset.
`creationTime`	No	Output only. The time when this dataset was created, in milliseconds since the epoch.
`friendlyName`	No	Optional. A descriptive name for the dataset.
`resourceTags`	No	Optional. The [tags](https://cloud.google.com/bigquery/docs/tags) attached to this dataset. Tag keys are globally unique. Tag key is expected to be in the namespaced format, for example "123456789012/environment" where 123456789012 is the ID of the parent organization or project resource for this tag key. Tag value is expected to be the short name, for example "Production". See [Tag definitions](https://cloud.google.com/iam/docs/tags-access-control#definitions) for more details.
`restrictions`	No	Optional. Output only. Restriction config for all tables and dataset. If set, restrict certain accesses on the dataset and all its tables based on the config. See [Data egress](https://cloud.google.com/bigquery/docs/analytics-hub-introduction#data_egress) for more details.
`satisfiesPzi`	No	Output only. Reserved for future use.
`satisfiesPzs`	No	Output only. Reserved for future use.
`catalogSource`	No	Output only. The origin of the dataset, one of: * (Unset) - Native BigQuery Dataset * BIGLAKE - Dataset is backed by a namespace stored natively in Biglake
`datasetReference`	No	Required. A reference that identifies the dataset.
`defaultCollation`	No	Optional. Defines the default collation specification of future tables created in the dataset. If a table is created in this dataset without table-level default collation, then the table inherits the dataset default collation, which is applied to the string fields that do not have explicit collation specified. A change to this field affects only tables created afterwards, and does not alter the existing tables. The following values are supported: * 'und:ci': undetermined locale, case insensitive. * '': empty string. Default to case-sensitive behavior.
`lastModifiedTime`	No	Output only. The date when this dataset was last modified, in milliseconds since the epoch.
`isCaseInsensitive`	No	Optional. TRUE if the dataset and its table names are case-insensitive, otherwise FALSE. By default, this is FALSE, which means the dataset and its table names are case-sensitive. This field does not affect routine references.
`maxTimeTravelHours`	No	Optional. Defines the time travel window in hours. The value can be from 48 to 168 hours (2 to 7 days). The default value is 168 hours if this is not set.
`defaultRoundingMode`	No	Optional. Defines the default rounding mode specification of new tables created within this dataset. During table creation, if this field is specified, the table within this dataset will inherit the default rounding mode of the dataset. Setting the default rounding mode on a table overrides this option. Existing tables in the dataset are unaffected. If columns are defined during that table creation, they will immediately inherit the table's default rounding mode, unless otherwise specified.
`linkedDatasetSource`	No	Optional. The source dataset reference when the dataset is of type LINKED. For all other dataset types it is not set. This field cannot be updated once it is set. Any attempt to update this field using Update and Patch API Operations will be ignored.
`storageBillingModel`	No	Optional. Updates storage_billing_model for the dataset.
`linkedDatasetMetadata`	No	Output only. Metadata about the LinkedDataset. Filled out when the dataset type is LINKED.
`defaultTableExpirationMs`	No	Optional. The default lifetime of all tables in the dataset, in milliseconds. The minimum lifetime value is 3600000 milliseconds (one hour). To clear an existing default expiration with a PATCH request, set to 0. Once this property is set, all newly-created tables in the dataset will have an expirationTime property set to the creation time plus the value in this property, and changing the value will only affect new tables, not existing ones. When the expirationTime for a given table is reached, that table will be deleted automatically. If a table's expirationTime is modified or removed before the table expires, or if you provide an explicit expirationTime when creating a table, that value takes precedence over the default expiration time indicated by this property.
`externalDatasetReference`	No	Optional. Reference to a read-only external dataset defined in data catalogs outside of BigQuery. Filled out when the dataset type is EXTERNAL.
`defaultPartitionExpirationMs`	No	This default partition expiration, expressed in milliseconds. When new time-partitioned tables are created in a dataset where this property is set, the table will inherit this value, propagated as the `TimePartitioning.expirationMs` property on the new table. If you set `TimePartitioning.expirationMs` explicitly when creating a table, the `defaultPartitionExpirationMs` of the containing dataset is ignored. When creating a partitioned table, if `defaultPartitionExpirationMs` is set, the `defaultTableExpirationMs` value is ignored and the table will not be inherit a table expiration deadline.
`externalCatalogDatasetOptions`	No	Optional. Options defining open source compatible datasets living in the BigQuery catalog. Contains metadata of open source database, schema or namespace represented by the current dataset.
`defaultEncryptionConfiguration`	No	The default encryption key for all tables in the dataset. After this property is set, the encryption key of all newly-created tables in the dataset is set to this value unless the table creation request or query explicitly overrides the key.

TDQS

A3.6/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds 'metadata information' but no extra behavioral context like response format or limitations. It does not contradict annotations.

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

Conciseness5/5

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

A single sentence that is front-loaded with the verb and resource, with no redundant wording. It is concise and well-structured.

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 simple metadata retrieval tool, the description is adequate. The output schema exists to define return values, and annotations cover safety. It could mention the relationship to sibling tools, but that is not essential for a straightforward get operation.

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% with clear descriptions for both projectId and datasetId. The tool description adds no additional parameter meaning, so the baseline of 3 applies.

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 clearly states the verb 'Get' and the resource 'metadata information about a BigQuery dataset or BigLake namespace'. It distinguishes from siblings like get_table_info (table metadata) and list_dataset_ids (listing IDs).

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

Usage Guidelines2/5

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 get_table_info or list_dataset_ids. It does not mention typical scenarios or exclusions, leaving the agent to infer context.

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

get_job

Read-onlyIdempotent

Inspect

Get information and status about a BigQuery job.

Use this tool to check the status, statistics, or configuration of a job using its job_id.

ParametersJSON Schema

Name	Required	Description
`jobId`	Yes	Required. Job ID of the requested job.
`location`	Yes	Required. The geographic location of the job.
`projectId`	Yes	Required. Project ID of the requested job.

Output Schema

ParametersJSON Schema

Name	Required	Description
`id`	No	Output only. Opaque ID field of the job.
`etag`	No	Output only. A hash of this resource.
`kind`	No	Output only. The type of the resource.
`status`	No	Output only. The status of this job. Examine this value when polling an asynchronous job to see if the job is complete.
`selfLink`	No	Output only. A URL that can be used to access the resource again.
`statistics`	No	Output only. Information about the job, including starting time and ending time of the job.
`user_email`	No	Output only. Email address of the user who ran the job.
`jobReference`	No	Optional. Reference describing the unique-per-user name of the job.
`configuration`	No	Required. Describes the job configuration.
`jobCreationReason`	No	Output only. The reason why a Job was created.
`principal_subject`	No	Output only. [Full-projection-only] String representation of identity of requesting party. Populated for both first- and third-party identities. Only present for APIs that support third-party identities.

get_query_results

Read-onlyIdempotent

Inspect

Get the results of a BigQuery SQL query job.

Use this tool ONLY when:

A previous execute_sql or execute_sql_readonly call returned job_complete: false with a job_id (poll with this tool until job_complete: true), OR
You need to paginate through additional rows using page_token or start_index for a previously completed job.

Do NOT call this tool if the query already returned job_complete: true with all rows.

Supports pagination. Use max_results to limit results and page_token to retrieve the next page of results.

ParametersJSON Schema

Name	Required	Description
`jobId`	Yes	Required. Job ID of the query job.
`location`	Yes	Required. The geographic location of the job.
`pageToken`	No	Optional. Page token, returned by a previous call, to request the next page of results.
`projectId`	Yes	Required. Project ID of the query job.
`timeoutMs`	No	Optional. Specifies the maximum amount of time, in milliseconds, that the client is willing to wait for the query to complete.
`maxResults`	No	Optional. Maximum number of results to read.
`startIndex`	No	Optional. Zero-based index of the starting row.

Output Schema

ParametersJSON 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.
`jobId`	No	Output only. The ID of the BigQuery job created for this query, if any. Present when a query job is created (e.g. for long-running operations, DML, scripts). Use this ID with `get_query_results`, `cancel_job`, or `get_job`.
`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.

get_table_infoA

Read-onlyIdempotent

Inspect

Get metadata information about a BigQuery table or BigLake table.

ParametersJSON Schema

Name	Required	Description
`tableId`	Yes	Required. Table ID of the table request.
`datasetId`	Yes	Required. Dataset ID of the table request.
`projectId`	Yes	Required. Project ID of the table request.

Output Schema

ParametersJSON Schema

Name	Required	Description
`id`	No	Output only. An opaque ID uniquely identifying the table.
`etag`	No	Output only. A hash of this resource.
`kind`	No	The type of resource ID.
`type`	No	Output only. Describes the table type. The following values are supported: * `TABLE`: A normal BigQuery table. * `VIEW`: A virtual table defined by a SQL query. * `EXTERNAL`: A table that references data stored in an external storage system, such as Google Cloud Storage. * `MATERIALIZED_VIEW`: A precomputed view defined by a SQL query. * `SNAPSHOT`: An immutable BigQuery table that preserves the contents of a base table at a particular time. See additional information on [table snapshots](https://cloud.google.com/bigquery/docs/table-snapshots-intro). The default value is `TABLE`.
`view`	No	Optional. The view definition.
`labels`	No	The labels associated with this table. You can use these to organize and group your tables. 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 values are optional. Label keys must start with a letter and each label in the list must have a different key.
`schema`	No	Optional. Describes the schema of this table.
`numRows`	No	Output only. The number of rows of data in this table, excluding any data in the streaming buffer.
`location`	No	Output only. The geographic location where the table resides. This value is inherited from the dataset.
`numBytes`	No	Output only. The size of this table in logical bytes, excluding any data in the streaming buffer.
`replicas`	No	Optional. Output only. Table references of all replicas currently active on the table.
`selfLink`	No	Output only. A URL that can be used to access this resource again.
`clustering`	No	Clustering specification for the table. Must be specified with time-based partitioning, data in the table will be first partitioned and subsequently clustered.
`description`	No	Optional. A user-friendly description of this table.
`creationTime`	No	Output only. The time when this table was created, in milliseconds since the epoch.
`friendlyName`	No	Optional. A descriptive name for this table.
`maxStaleness`	No	Optional. The maximum staleness of data that could be returned when the table (or stale MV) is queried. Staleness encoded as a string encoding of sql IntervalValue type.
`resourceTags`	No	Optional. The [tags](https://cloud.google.com/bigquery/docs/tags) attached to this table. Tag keys are globally unique. Tag key is expected to be in the namespaced format, for example "123456789012/environment" where 123456789012 is the ID of the parent organization or project resource for this tag key. Tag value is expected to be the short name, for example "Production". See [Tag definitions](https://cloud.google.com/iam/docs/tags-access-control#definitions) for more details.
`restrictions`	No	Optional. Output only. Restriction config for table. If set, restrict certain accesses on the table based on the config. See [Data egress](https://cloud.google.com/bigquery/docs/analytics-hub-introduction#data_egress) for more details.
`numPartitions`	No	Output only. The number of partitions present in the table or materialized view. This data is not kept in real time, and might be delayed by a few seconds to a few minutes.
`expirationTime`	No	Optional. The time when this table expires, in milliseconds since the epoch. If not present, the table will persist indefinitely. Expired tables will be deleted and their storage reclaimed. The defaultTableExpirationMs property of the encapsulating dataset can be used to set a default expirationTime on newly created tables.
`tableReference`	No	Required. Reference describing the ID of this table.
`cloneDefinition`	No	Output only. Contains information about the clone. This value is set via the clone operation.
`streamingBuffer`	No	Output only. Contains information regarding this table's streaming buffer, if one is present. This field will be absent if the table is not being streamed to or if there is no data in the streaming buffer.
`defaultCollation`	No	Optional. Defines the default collation specification of new STRING fields in the table. During table creation or update, if a STRING field is added to this table without explicit collation specified, then the table inherits the table default collation. A change to this field affects only fields added afterwards, and does not alter the existing fields. The following values are supported: * 'und:ci': undetermined locale, case insensitive. * '': empty string. Default to case-sensitive behavior.
`lastModifiedTime`	No	Output only. The time when this table was last modified, in milliseconds since the epoch.
`managedTableType`	No	Optional. If set, overrides the default managed table type configured in the dataset.
`materializedView`	No	Optional. The materialized view definition.
`numLongTermBytes`	No	Output only. The number of logical bytes in the table that are considered "long-term storage".
`numPhysicalBytes`	No	Output only. The physical size of this table in bytes. This includes storage used for time travel.
`tableConstraints`	No	Optional. Tables Primary Key and Foreign Key information
`timePartitioning`	No	If specified, configures time-based partitioning for this table.
`rangePartitioning`	No	If specified, configures range partitioning for this table.
`snapshotDefinition`	No	Output only. Contains information about the snapshot. This value is set via snapshot creation.
`defaultRoundingMode`	No	Optional. Defines the default rounding mode specification of new decimal fields (NUMERIC OR BIGNUMERIC) in the table. During table creation or update, if a decimal field is added to this table without an explicit rounding mode specified, then the field inherits the table default rounding mode. Changing this field doesn't affect existing fields.
`partitionDefinition`	No	Optional. The partition information for all table formats, including managed partitioned tables, hive partitioned tables, iceberg partitioned, and metastore partitioned tables. This field is only populated for metastore partitioned tables. For other table formats, this is an output only field.
`biglakeConfiguration`	No	Optional. Specifies the configuration of a BigQuery table for Apache Iceberg.
`numTotalLogicalBytes`	No	Output only. Total number of logical bytes in the table or materialized view.
`tableReplicationInfo`	No	Optional. Table replication info for table created `AS REPLICA` DDL like: `CREATE MATERIALIZED VIEW mv1 AS REPLICA OF src_mv`
`numActiveLogicalBytes`	No	Output only. Number of logical bytes that are less than 90 days old.
`numTotalPhysicalBytes`	No	Output only. The physical size of this table in bytes. This also includes storage used for time travel. This data is not kept in real time, and might be delayed by a few seconds to a few minutes.
`materializedViewStatus`	No	Output only. The materialized view status.
`numActivePhysicalBytes`	No	Output only. Number of physical bytes less than 90 days old. This data is not kept in real time, and might be delayed by a few seconds to a few minutes.
`requirePartitionFilter`	No	Optional. If set to true, queries over this table require a partition filter that can be used for partition elimination to be specified.
`encryptionConfiguration`	No	Custom encryption configuration (e.g., Cloud KMS keys).
`numCurrentPhysicalBytes`	No	Output only. Number of physical bytes used by current live data storage. This data is not kept in real time, and might be delayed by a few seconds to a few minutes.
`numLongTermLogicalBytes`	No	Output only. Number of logical bytes that are more than 90 days old.
`numLongTermPhysicalBytes`	No	Output only. Number of physical bytes more than 90 days old. This data is not kept in real time, and might be delayed by a few seconds to a few minutes.
`externalDataConfiguration`	No	Optional. Describes the data format, location, and other properties of a table stored outside of BigQuery. By defining these properties, the data source can then be queried as if it were a standard BigQuery table.
`numTimeTravelPhysicalBytes`	No	Output only. Number of physical bytes used by time travel storage (deleted or changed data). This data is not kept in real time, and might be delayed by a few seconds to a few minutes.
`externalCatalogTableOptions`	No	Optional. Options defining open source compatible table.

TDQS

A3.9/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to restate these. The description adds no extra behavioral context, but the annotations are sufficient to establish non-modifying behavior, so a higher score is appropriate.

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

Conciseness5/5

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

The description is a single, clear sentence with no redundancy or extraneous information. It directly states the tool's function without unnecessary detail, 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.

Completeness5/5

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

Given the simplicity of the tool (retrieving metadata for a single table), the description and fully-annotated input schema are adequate. The presence of an output schema means return values do not need to be explained in the description, and no edge cases or limitations are relevant for this straightforward operation.

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% with each parameter having a description, meeting the high-coverage baseline. However, the parameter descriptions are terse and redundant (e.g., 'Table ID of the table request'), adding little semantic value beyond the parameter names themselves.

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 clearly states the verb 'Get' and the resource 'metadata information about a BigQuery table or BigLake table'. It is distinguishable from sibling tools like get_dataset_info or list_table_ids by its specific focus on a single table's metadata.

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

Usage Guidelines2/5

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

The description does not provide explicit guidance on when to use this tool versus alternatives such as execute_sql_readonly for metadata queries. It lacks any mention of use cases or exclusion criteria, leaving the agent to infer usage from the name alone.

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

list_dataset_idsA

Read-onlyIdempotent

Inspect

List BigQuery dataset IDs and BigLake namespaces in a Google Cloud project. Supports pagination. Use page_size to limit results and page_token to retrieve next page.

ParametersJSON Schema

Name	Required	Description
`pageSize`	No	Optional. The maximum number of results to return in a single response page. If unset, the default page size of 5000 is used.
`pageToken`	No	Optional. Page token, returned by a previous call, to request the next page of results.
`projectId`	Yes	Required. Project ID of the dataset request.

Output Schema

ParametersJSON Schema

Name	Required	Description
`datasets`	No	The datasets that matched the request.
`nextPageToken`	No	A token that can be used to request the next results page.

TDQS

A4.8/5.0

Behavior5/5

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) cover behavioral aspects, and the description does not contradict them. The mention of pagination adds transparency about result streaming.

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

Conciseness5/5

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

The description is concise, with two sentences that state the action and pagination usage. It is front-loaded and contains no redundant information.

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

Completeness5/5

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

The description indicates the output (dataset IDs and BigLake namespaces) and the presence of an output schema (though not shown) means return values are already defined. No additional context is needed for a listing operation.

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

Parameters5/5

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

All three parameters (projectId, pageSize, pageToken) are described in the schema with clear meanings, and the description also references page_size and page_token, achieving 100% coverage.

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 clearly states the tool lists BigQuery dataset IDs and BigLake namespaces in a project, using the specific verb 'List' and identifying the resource. It distinguishes itself from siblings like list_table_ids, which lists table IDs.

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

Usage Guidelines4/5

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

The description provides explicit pagination instructions ('Use page_size to limit results and page_token to retrieve next page') and indicates the tool supports pagination. It does not explicitly contrast with sibling tools, but the purpose is clear enough for typical use.

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

list_table_idsA

Read-onlyIdempotent

Inspect

List table ids in a BigQuery dataset or BigLake namespace. Supports pagination. Use page_size to limit results and page_token to retrieve next page.

ParametersJSON Schema

Name	Required	Description
`pageSize`	No	Optional. The maximum number of results to return in a single response page. If unset, the default page size of 5000 is used.
`datasetId`	Yes	Required. Dataset ID of the table request.
`pageToken`	No	Optional. Page token, returned by a previous call, to request the next page of results.
`projectId`	Yes	Required. Project ID of the table request.

Output Schema

ParametersJSON Schema

Name	Required	Description
`tables`	No	The tables that matched the request.
`nextPageToken`	No	A token that can be used to request the next results page.

TDQS

A4.1/5.0

Behavior4/5

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

The annotations already signal read-only/idempotent/non-destructive behavior, and the description adds the pagination behavior. It does not describe potential errors or permissions, but annotations adequately cover the key side-effect profile.

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

Conciseness5/5

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

The description is two sentences, front-loaded with the core purpose, and contains no unnecessary detail.

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

Completeness5/5

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

For a simple listing tool with pagination and an output schema, the description is complete: it states the scope, pagination support, and how to use the pagination parameters. The output schema is available, so return-value details are not required in the description.

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 coverage is 100%, and the description adds semantic meaning for pageSize/pageToken. However, it refers to them as 'page_size' and 'page_token' in snake_case, while the actual schema properties are camelCase, which is a minor mismatch that could cause confusion.

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 clearly states the action ('List') and the resource ('table ids in a BigQuery dataset or BigLake namespace'), making it distinct from sibling tools like list_dataset_ids or get_table_info.

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

Usage Guidelines3/5

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

It provides pagination guidance ('Use page_size to limit results and page_token to retrieve next page') but does not explicitly explain when to choose this tool over alternative siblings such as execute_sql or list_dataset_ids.

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