Skip to main content
Glama

NS Pros MCP Gateway

google-bigquery__execute_sql

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', 

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "projectId": "<projectId>",
      "query": "<query>"
    },
    "name": "google-bigquery__execute_sql"
  }
}

Input Schema

NameRequiredDescriptionDefault
queryYesRequired. The query to execute in the form of a GoogleSQL query.
dryRunNoOptional. 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.
labelsNoOptional. 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.
projectIdYesRequired. Project that will be used for query execution and billing.
timeoutMsNoOptional. 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).
jobTimeoutMsNoOptional. Optional: Job timeout in milliseconds. If this time limit is exceeded, BigQuery will attempt to stop the query job.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A3.7/5.0
Behavior3/5

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

No annotations are supplied, so the description carries the whole burden. It does disclose the important trait that this tool executes mutating and destructive statements (INSERT/UPDATE/DELETE/CREATE), which is real value. But it says nothing about billing/cost of the query (bytes processed), required IAM permissions, what happens when the timeout is hit, or that DML is irreversible — all of which matter for a mutation-capable tool.

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 opening routing sentence is correctly front-loaded and the support-enumeration bullets are efficient. The example section, however, is truncated mid-statement ("VALUES ('Alice', "), so a meaningful chunk of the description is wasted and the agent receives a broken code sample.

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

Completeness3/5

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

For a 6-parameter, mutation-capable query tool with no annotations and no output schema, the description establishes what it runs and the timeout-based synchronous behavior. It omits how results come back (rows vs. job reference), what to do when a long query exceeds the timeout (the `get_job`/`get_query_results` siblings exist for exactly this), and cost/permission caveats.

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 `dryRun`, `labels`, `timeoutMs`, `jobTimeoutMs` and `projectId` are already fully documented in structured fields; the baseline is 3. The description adds nothing about when to use `dryRun` as a pre-flight check or how the two timeout parameters differ, so it does not exceed 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?

States a specific verb and resource ('Run a SQL query in the project and return the result') and immediately scopes it against the sibling by naming `execute_sql_readonly` as the preferred path. The bullet list of supported query classes (SELECT/INSERT/UPDATE/DELETE/CREATE, AI/ML functions) makes the capability envelope unambiguous.

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?

'Prefer the `execute_sql_readonly` tool if possible' gives an explicit routing rule toward the safer alternative, which implies this tool is for statements that cannot run read-only. However it never spells out the exclusion directly (e.g. 'use only for DDL/DML or jobs that must mutate state'), so the agent must infer the boundary rather than read it.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.