What your AI sees - UniversalBench

Your AI agent sees UniversalBench as three purpose-built tools: ub_read for read-only queries, ub_write for code execution and writes, and ub_ai for web search and LLM calls. Each tool accepts multiple optional input fields. Your AI picks the right tool based on what it needs to do.

What is in the AI context

When your AI client connects to UniversalBench, it pulls a tool list like this:

{
  "tools": [
    {
      "name": "ub_read",
      "description": "Read-only capabilities: database queries, GitHub reads, file reads, source validation.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "db_select": { "type": "object", "description": "Structured query with filters, ordering, and limit" },
          "db_query": { "type": "object", "description": "Raw SELECT statement" },
          "db_search": { "type": "object", "description": "Keyword search across text columns" },
          "git_read": { "type": "object", "description": "Read a file from a GitHub repository" },
          "file_read": { "type": "string", "description": "Read a file from the session filesystem" },
          "validate_file": { "type": "string", "description": "Static check on Python source" },
          "session_id": { "type": "string", "description": "Session identifier for shared state" }
        }
      }
    },
    {
      "name": "ub_write",
      "description": "Code execution and state-modifying operations: Python, bash, file writes, database writes, GitHub commits, secrets vault, HTTP.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "code": { "type": "string", "description": "Python code to run in a sandboxed environment" },
          "bash": { "type": "string", "description": "Shell command to run" },
          "parallel_blocks": { "type": "array", "description": "Up to eight code blocks to run concurrently" },
          "install_packages": { "type": "array", "description": "Python packages to install before the call" },
          "file_write": { "type": "object", "description": "Write a file to the session filesystem" },
          "db_write": { "type": "object", "description": "Insert or update rows in your database" },
          "db_upsert": { "type": "object", "description": "Upsert a row by conflict column" },
          "git_push": { "type": "object", "description": "Push a file to GitHub with built-in validation" },
          "code_edit": { "type": "object", "description": "Single-anchor find and replace, ambiguity rejected" },
          "safe_deploy": { "type": "object", "description": "Push with smoke test and automatic rollback" },
          "proxy_http": { "type": "object", "description": "Outbound HTTP call with network safety guards" },
          "secrets_vault": { "type": "object", "description": "Encrypted per-customer secret storage" },
          "session_id": { "type": "string", "description": "Session identifier for persistent state" }
        }
      }
    },
    {
      "name": "ub_ai",
      "description": "AI and live web capabilities. Additional provider cost per call.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "web_search": { "type": "string", "description": "Search the web for live results" },
          "invoke_llm": { "type": "string", "description": "Call any major LLM with cost safety" }
        }
      }
    }
  ]
}

Each input is independent. Your AI fills in whichever fields it needs for a given call. Most calls use one or two fields.

Why three tools with multiple inputs each

The three-tool split keeps intent clear. ub_read is always safe to call, ub_write changes state, ub_ai has additional cost. Your AI makes better decisions when the tool name already signals the category. Within each tool, capabilities are input fields rather than separate tools. This keeps the schema compact and reduces the chance of your AI hallucinating a tool name.

How to help your AI choose well

1. Name the capability you want

If you want a specific input field, name it. AIs are good at fuzzy matching but explicit is always faster.

Use UniversalBench to search the web for current data on solar panel efficiency

instead of

Look up some current information about solar panels

2. Pass context once

If your task involves the same dataset or session across many calls, mention it at the top of the conversation. Most MCP clients carry context across turns.

We are working in session_id q3_analysis for this entire conversation. Load the CSV once and reuse the dataframe.

3. Trust the sandbox

Code runs in a sandboxed environment. You do not need to add “be careful” warnings. Be specific about what you want and let UniversalBench handle the execution.

What your AI does not see

Your URL token (the client holds the URL, never echoes the token back into the AI context)
Other customers’ data (every call is scoped to the customer your URL belongs to)
The workbench internal state from previous calls (unless you pass session_id)
Stored secret values (only their names appear in tool calls)

Because auth lives in the URL path and not in your prompts, even a fully recorded conversation transcript does not expose your credentials.

​What is in the AI context

​Why three tools with multiple inputs each

​How to help your AI choose well

​1. Name the capability you want

​2. Pass context once

​3. Trust the sandbox

​What your AI does not see