Tools - UniversalBench

UniversalBench exposes three MCP tools. ub_read handles read-only work using your own credentials. ub_write handles code execution and state-modifying operations. ub_ai handles AI and live web capabilities. Set one or more fields per call within each tool.

ub_read

Read-only operations using your own credentials. Includes database queries, file access, repository reads, and source validation. UniversalBench can connect to any PostgreSQL-compatible database. Provide your database URL and key via the secrets vault and the database inputs auto-inject them.

db_select

Structured query with filters, ordering, and limit. The idiomatic read API.

{
  "name": "ub_read",
  "arguments": {
    "db_select": {
      "table": "orders",
      "filters": [["status", "eq", "shipped"], ["created_at", "gte", "2026-01-01"]],
      "order": "-created_at",
      "limit": 50,
      "select": "id,total,customer_id"
    }
  }
}

Filter operators include eq, neq, gt, gte, lt, lte, like, ilike, in_. Order strings prefix - for descending. Select picks specific columns or * for all.

db_query

Best effort SQL parse for SELECT ... FROM tbl [WHERE ...] [ORDER BY ...] [LIMIT N]. Convenient when your AI already wrote the SQL.

{
  "name": "ub_read",
  "arguments": {
    "db_query": "SELECT id, email FROM customers WHERE tier = 'pro' LIMIT 20"
  }
}

For anything beyond plain SELECT, prefer db_select for filters and ub_write code for joins or aggregations.

db_search

Case insensitive keyword search across one or more text columns.

{
  "name": "ub_read",
  "arguments": {
    "db_search": {
      "table": "knowledge_base",
      "columns": ["title", "body"],
      "query": "refund policy"
    }
  }
}

file_read

Read a file from the workbench filesystem. Returns the file content as text.

{ "name": "ub_read", "arguments": { "file_read": "/tmp/data.csv" } }

Files must be under /tmp. Files written by ub_write code calls in the same session persist for that session.

git_read

Read a file from a GitHub repository. Returns content and the file SHA. Works on private repositories.

{
  "name": "ub_read",
  "arguments": {
    "git_read": {
      "owner": "your-org",
      "repo": "your-repo",
      "path": "src/index.js",
      "ref": "main"
    }
  }
}

Provide GITHUB_TOKEN via the secrets vault and it auto-injects into every git_read call.

validate_file

Static check on Python source. Returns an issues list and, where possible, a fixed version.

{ "name": "ub_read", "arguments": { "validate_file": "import os\ndef foo():\n  return os.path.exsts('/tmp')" } }

session_id

Pass a session identifier to share warm session state with ub_write calls using the same ID.

{
  "name": "ub_read",
  "arguments": {
    "session_id": "my_pipeline",
    "file_read": "/tmp/data.csv"
  }
}

google_ads_research

Read a connected Google Ads account: keyword ideas with monthly search volume and competition, whether your live ads are approved, performance reports (per campaign, per search term, per keyword), the structure of your campaigns and ad groups, and your conversion actions. Pass a plain keyword string for quick ideas, or an object with an operation. Operations: keyword_research, status, accounts, report_campaigns, report_search_terms, report_keywords, structure, conversion_actions. Reports accept a date_range such as LAST_7_DAYS or LAST_30_DAYS, or explicit start_date and end_date. Quick keyword ideas:

{ "name": "ub_read", "arguments": { "google_ads_research": "running shoes" } }

Read the account structure to get campaign, ad group, and keyword resource names:

{ "name": "ub_read", "arguments": { "google_ads_research": { "operation": "structure" } } }

A last-7-days campaign performance report:

{ "name": "ub_read", "arguments": { "google_ads_research": { "operation": "report_campaigns", "date_range": "LAST_7_DAYS" } } }

If the account has not connected Google Ads access yet, the reply returns a connect link.

ub_write

Code execution and state-modifying operations. Runs in an isolated sandbox. Includes compute, file writes, database writes, GitHub operations, secrets management, and outbound HTTP.

code

Run Python in a sandboxed environment. Returns stdout, stderr, and execution time.

{
  "name": "ub_write",
  "arguments": {
    "code": "import math; print(math.pi * 2)"
  }
}

The sandbox includes the Python standard library, common scientific packages (requests, pandas, numpy, etc.), and any packages you install via install_packages. The execution timeout is 60 seconds.

bash

Run a shell command. Returns stdout and stderr.

{ "name": "ub_write", "arguments": { "bash": "ls -la /tmp" } }

The working directory is /tmp. Most standard Linux utilities are available. The execution timeout is 60 seconds.

parallel_blocks

Run up to eight code blocks concurrently in one call. Returns a list of results in input order.

{
  "name": "ub_write",
  "arguments": {
    "parallel_blocks": [
      { "code": "import time; time.sleep(1); print('one')" },
      { "code": "import time; time.sleep(1); print('two')" },
      { "code": "import time; time.sleep(1); print('three')" }
    ]
  }
}

Three blocks that each sleep one second take one second total, not three. Useful for independent fetches, parallel data analysis, or fan out queries.

install_packages

Install Python packages before the call. Returns the install log.

{
  "name": "ub_write",
  "arguments": {
    "install_packages": ["beautifulsoup4", "lxml"],
    "code": "from bs4 import BeautifulSoup; print('installed')"
  }
}

Installed packages persist for the duration of the session. Common packages are already preinstalled and do not need to be listed.

file_write

Write a file to the workbench filesystem.

{
  "name": "ub_write",
  "arguments": {
    "file_write": {
      "path": "/tmp/output.json",
      "content": "{\"status\": \"ok\"}"
    }
  }
}

Paths must be under /tmp. Combine with session_id to keep written files available for the next call in the same session.

db_write

Insert one row, or update rows matching a filter.

{
  "name": "ub_write",
  "arguments": {
    "db_write": {
      "table": "events",
      "row": { "type": "signup", "email": "new@example.com" }
    }
  }
}

{
  "name": "ub_write",
  "arguments": {
    "db_write": {
      "table": "customers",
      "filter": [["id", "eq", "cust_123"]],
      "update": { "tier": "pro" }
    }
  }
}

db_upsert

Upsert one row using one or more conflict columns.

{
  "name": "ub_write",
  "arguments": {
    "db_upsert": {
      "table": "customer_state",
      "row": { "customer_id": "cust_123", "last_seen_at": "2026-05-17T10:00:00Z" },
      "on_conflict": "customer_id"
    }
  }
}

git_push

Push a file to GitHub. Returns the commit SHA on success.

{
  "name": "ub_write",
  "arguments": {
    "git_push": {
      "owner": "your-org",
      "repo": "your-repo",
      "path": "src/index.js",
      "content": "// new file content",
      "message": "feat: add new module",
      "branch": "main",
      "sha": "abc123def456"
    }
  }
}

For .py files, Python is validated before the push lands. Files that would crash at runtime are rejected before they reach your repository. Your AI cannot ship broken Python through UniversalBench.

code_diff

Run two code blocks and compare their outputs. Useful for verifying that a refactor did not change behaviour.

{
  "name": "ub_write",
  "arguments": {
    "code_diff": {
      "old_code": "def f(x): return x*2",
      "new_code": "def f(x): return x+x"
    }
  }
}

Returns the output diff if the two diverge on the same inputs.

code_edit

Single anchor find and replace on a file. Pass the old text and the new text. Ambiguous matches are rejected.

{
  "name": "ub_write",
  "arguments": {
    "code_edit": {
      "path": "/tmp/script.py",
      "old": "TIMEOUT = 30",
      "new": "TIMEOUT = 60"
    }
  }
}

When the anchor appears more than once, the edit is rejected with the count rather than silently editing the wrong place.

safe_deploy

Push a file and run a smoke test against a URL after the push lands. If the smoke test fails, the push is rolled back automatically.

{
  "name": "ub_write",
  "arguments": {
    "safe_deploy": {
      "owner": "your-org",
      "repo": "your-repo",
      "path": "src/index.js",
      "content": "// new content",
      "message": "feat: ship new feature",
      "smoke_test_url": "https://your-app.com/health"
    }
  }
}

proxy_http

Make an outbound HTTP call from the workbench. Returns status, headers, body, and bytes received.

{
  "name": "ub_write",
  "arguments": {
    "proxy_http": {
      "method": "GET",
      "url": "https://api.github.com/repos/octocat/Hello-World",
      "headers": { "Accept": "application/vnd.github+json" },
      "timeout": 15
    }
  }
}

Only http and https schemes are accepted. Internal network addresses and cloud metadata endpoints are blocked to prevent server side request forgery. Response bodies above a fixed cap are truncated and flagged in the response.

secrets_vault

Encrypted per customer secret storage. Values are encrypted at rest. Your AI references secrets by name, never by value.

The action is save (not set or store), the name field is secret_name (not key or name), and the value field is secret_value (not value). Getting one of these wrong is the most common vault error. See Troubleshooting.

Save a secret:

{
  "name": "ub_write",
  "arguments": {
    "secrets_vault": {
      "action": "save",
      "secret_name": "STRIPE_KEY",
      "secret_value": "sk_live_xxx"
    }
  }
}

List secret names (values are never returned):

{ "name": "ub_write", "arguments": { "secrets_vault": { "action": "list" } } }

Retrieve a secret value:

{ "name": "ub_write", "arguments": { "secrets_vault": { "action": "get", "secret_name": "STRIPE_KEY" } } }

Delete a secret permanently:

{ "name": "ub_write", "arguments": { "secrets_vault": { "action": "delete", "secret_name": "OLD_KEY" } } }

Secrets are scoped to your account. Other customers cannot read them. Common credentials like SUPABASE_URL, SUPABASE_KEY, and GITHUB_TOKEN are auto-injected into matching tools so your AI never needs to read the value.

session_id and clear_session

Pass session_id to keep Python variables, imports, and connections warm across calls:

{
  "name": "ub_write",
  "arguments": {
    "session_id": "my_pipeline",
    "code": "import pandas as pd; df = pd.read_csv('/tmp/data.csv')"
  }
}

Subsequent calls with the same session_id can reference df and pd without redoing the work. Sessions expire after a period of inactivity. Pass clear_session: true to wipe all state before processing the call:

{
  "name": "ub_write",
  "arguments": {
    "session_id": "my_pipeline",
    "clear_session": true,
    "code": "print('fresh session')"
  }
}

task

Optional. A natural-language description of what this call is doing. Used for telemetry and adaptive timeout tuning only. Has no effect on execution.

{
  "name": "ub_write",
  "arguments": {
    "task": "build month-over-month revenue chart",
    "code": "..."
  }
}

Combining inputs

You can set multiple input fields in one ub_write call:

{
  "name": "ub_write",
  "arguments": {
    "install_packages": ["yfinance"],
    "code": "import yfinance as yf; print(yf.Ticker('AAPL').info['currentPrice'])"
  }
}

This installs yfinance and runs the code in one call, billed as one call.

google_ads

Manage a connected Google Ads account end to end. Build campaigns, ad groups, keywords, and responsive search ads, upload image assets, and add a video ad. Set targeting: locations and proximity, ad schedules, languages, device bid adjustments, and audiences. Set bidding (manual CPC, maximize conversions, maximize conversion value, target CPA, target ROAS, maximize clicks) and budgets. Add ad extensions: sitelinks, callouts, structured snippets, call extensions, promotions, and prices. Set up conversion tracking, which returns the tracking snippet to install on your site. Edit a live account: pause or launch campaigns, ad groups, and keywords, change budgets and bids, add negative keywords, and remove items.

New entities are created paused, so nothing spends until you launch it. Any change that can spend money or remove something (launching or enabling anything, raising a budget, changing the bidding strategy, removing an item) returns a short approval request describing the exact change. Relay it to the user, then call again with confirm set to once to do it this time, or always to allow that kind of change for this account from now on. Every change is recorded.

Pass an object with an operation. Build: create_campaign, create_ad_group, add_keywords, create_rsa, upload_image_asset, create_video_ad. Targeting: add_geo_target, add_ad_schedule, set_language_target, set_device_bid_modifier, add_audience. Bidding and budget: set_bidding_strategy, update_campaign_budget. Extensions: create_sitelink, create_callout, create_structured_snippet, create_call_extension, create_promotion, create_price. Conversion tracking: create_conversion_action. Manage: update_campaign_status, update_ad_group_status, update_ad_group_bid, update_keyword_status, update_keyword_bid, add_negative_keywords, remove_campaign, remove_ad_group, remove_keyword, remove_ad.

All money is in micros: multiply the currency amount by 1,000,000, so 50 units is 50000000. Get campaign, ad group, and keyword resource names from google_ads_research with the structure operation first. If a change is rejected, the reply tells you exactly what to fix and what to read, so relay that and retry. For the exact fields of any operation, call how_to on ub_read with the name google_ads.

Create a campaign (created paused, nothing spends):

{ "name": "ub_write", "arguments": { "google_ads": { "operation": "create_campaign", "name": "Spring Sale", "daily_budget_micros": 50000000 } } }

Launch a campaign (spend-affecting, needs approval):

{ "name": "ub_write", "arguments": { "google_ads": { "operation": "update_campaign_status", "campaign": "1234567890", "status": "ENABLED", "confirm": "once" } } }

Set a bidding strategy:

{ "name": "ub_write", "arguments": { "google_ads": { "operation": "set_bidding_strategy", "campaign": "1234567890", "strategy": "target_cpa", "target_cpa_micros": 25000000, "confirm": "once" } } }

Set up conversion tracking (returns the snippet to install on your site):

{ "name": "ub_write", "arguments": { "google_ads": { "operation": "create_conversion_action", "name": "Purchase" } } }

ub_ai

AI and live web capabilities. Each ub_ai call incurs an additional provider cost on top of the base per-call rate.

web_search

Search the web for live results. Returns the top five results with title, snippet, and URL.

{ "name": "ub_ai", "arguments": { "web_search": "latest GPT model releases" } }

Results are real time and include source URLs.

invoke_llm

Call any major LLM. A prompt string goes in, the completion string comes out.

{ "name": "ub_ai", "arguments": { "invoke_llm": "Write a haiku about distributed systems" } }

The default model is a cost-efficient one. To route to a specific model, prefix your prompt with model=<name>;, for example model=claude-3-5-sonnet; Write a haiku.... Your AI platform’s tool description lists available model identifiers.

Database setup

Connect to any PostgreSQL-compatible database. Save your database URL and key as named secrets via secrets_vault. Name them SUPABASE_URL and SUPABASE_KEY and they auto-inject on every call.

GitHub setup

Save a personal access token in secrets_vault under the name GITHUB_TOKEN. The git_read, git_push, code_edit, and safe_deploy fields auto-inject it on every call.

The name must be GITHUB_TOKEN. If you save the token under another name such as GIT_PAT or with a typo, the GitHub fields cannot find it and every git_* call fails. If that happens, see Troubleshooting.

​ub_read

​db_select

​db_query

​db_search

​file_read

​git_read

​validate_file

​session_id

​google_ads_research

​ub_write

​code

​bash

​parallel_blocks

​install_packages

​file_write

​db_write

​db_upsert

​git_push

​code_diff

​code_edit

​safe_deploy

​proxy_http

​secrets_vault

​session_id and clear_session

​task

​Combining inputs

​google_ads

​ub_ai

​web_search

​invoke_llm

​Database setup

​GitHub setup

ub_read

db_select

db_query

db_search

file_read

git_read

validate_file

session_id

google_ads_research

ub_write

code

bash

parallel_blocks

install_packages

file_write

db_write

db_upsert

git_push

code_diff

code_edit

safe_deploy

proxy_http

secrets_vault

session_id and clear_session

task

Combining inputs

google_ads

ub_ai

web_search

invoke_llm

Database setup

GitHub setup