> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oqoqo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

> Add skills, MCP servers, CLIs, and SDKs by hand or from GitHub, give them the values they need, and mark official versions.

**Tools** are the skills, MCP servers, CLIs, and SDKs that your product provides to agents. Add them under **Manage → Tools**, then group them into [treatments](https://docs.oqoqo.ai/experiments/treatments.md) to measure how much each tool helps. (These are distinct from the [Oqoqo Plugin](https://docs.oqoqo.ai/operate/plugin.md) and [CLI](https://docs.oqoqo.ai/operate/cli.md), which operate Oqoqo itself.)

![Tools page with a box for MCP servers, Skills, CLIs, and SDKs, each with its count and a Needs values label where a value is missing.](https://mintcdn.com/oqoqo/YO1ysyUx4SPwBwoz/images/screenshots/tools-light.png?fit=max\&auto=format\&n=YO1ysyUx4SPwBwoz\&q=85\&s=dc94e1474493e7e482931d46a0f6e861)

## Tool types

| Tool | What it provides | What to look for in results |
| - | - | - |
| **Skill** | A folder with a `SKILL.md` guide and helper files | Whether agents load the skill and show positive pass-rate lift |
| **MCP server** | Remote or local tools exposed over MCP | Whether agents discover and select the right tool cleanly |
| **CLI** | A command-line binary installed on the run machine | Whether `--help`, flags, and errors guide the agent |
| **SDK** | A library agents install and import in code | Whether method signatures, docs, and types prevent mistakes |

Every tool is versioned, and each experiment locks the versions it launched with. A tool's **Experiments**, **Runs**, and **Frictions** tabs track every run across versions where a treatment included that tool.

## Skills

Open **Manage → Tools → Skills**, select **Add skills**, and drop a folder, `.zip`, or `.skill` file—or import [**From GitHub**](#import-from-github). One upload can import multiple skills at once.

Each skill takes the `name` field inside its `SKILL.md` regardless of folder depth (for example, `skills/cloud/onboarding/SKILL.md` with `name: cloud-onboarding` imports as `cloud-onboarding`). Oqoqo skips identical duplicates; if two skills share a `name` with different contents, rename one or import them separately. To save updates, open the skill and select **Import new version**.

## MCP servers

Open **Manage → Tools → MCP servers**, select **New MCP server**, and choose a **Transport**:

| Transport | When to use it |
| - | - |
| **HTTP** | Standard remote MCP servers |
| **SSE** | Remote servers that document Server-Sent Events |
| **Local** | A command executed inside the run machine with **Arguments** and **Environment variables** |

* **Network reachability:** **HTTP** and **SSE** servers must be reachable over public HTTPS from Oqoqo's cloud machines. **Local** servers run inside the task machine during runs, so Oqoqo cannot inspect their tools outside a run.
* **Test data and auto-approval:** Cloud runs auto-approve every MCP tool call—including tools marked `destructiveHint` or `_meta["anthropic/requiresUserInteraction"]`—so always point tasks at test accounts and data agents can safely modify.
* **Credentials & secrets:** Enter header values and personal OAuth logins only in the dashboard ([Add the values a tool needs](#add-the-values-a-tool-needs)). If you save a new server URL via the CLI or plugin, saved values stay unbound until you select **Refresh** on the version's **Tools** tab ([Saved header values and the server address](#saved-header-values-and-the-server-address)).

For remote servers, enter the **URL** (authentication switches automatically when OAuth is detected, or choose between **Sign in with provider** and **API key or token**):

* **Sign in with provider**: OAuth per team member (only you can run with your connection). Identity providers such as Okta, Google, or GitHub may require [your own OAuth app](https://docs.oqoqo.ai/experiments/mcp-server-sign-in.md).
* **API key or token**: shared secret headers entered in **Headers** for everyone in the project.

Use **Additional headers** for extra headers (such as a workspace ID), or **View as JSON** to edit the full definition.

### Keys in a URL or an argument

To pass a secret in a remote URL path or query (`https://mcp.example.com/mcp?apiKey=${EXA_API_KEY}`), or in a local server's arguments, use `${NAME}` instead of the raw key. Then declare `NAME` under **Headers** (for remote servers) or **Environment variables** (for local servers).

* `${NAME}` works in URL paths and query parameters (not hosts, ports, or fragments) and is injected at runtime so agents never see remote secrets.
* In local shell scripts (such as `sh -c '…'`), double-quote `"$NAME"` or `"${NAME}"`.

> [tab] Dashboard
>
> Enter `https://mcp.example.com/mcp?apiKey=${EXA_API_KEY}` as the **URL**, add `EXA_API_KEY` under **Headers** with your secret, and select **Save**.

> [tab] CLI
>
> Declare the key name in `headerNames` (or `envNames` for local servers) and apply the JSON, then enter the secret at the returned `setupUrl`:
>
> ```json theme={null}
> {
>   "action": "create",
>   "kind": "mcp",
>   "mutationAttemptId": "create-exa-mcp-01",
>   "name": "Exa",
>   "definition": {
>     "transport": "http",
>     "url": "https://mcp.example.com/mcp?apiKey=${EXA_API_KEY}",
>     "headerNames": ["EXA_API_KEY"]
>   }
> }
> ```
>
> ```bash theme={null}
> oqoqo resources apply --operation-file exa.json
> ```

> [tab] Plugin (MCP)
>
> Ask your AI assistant to add the server; it calls **Create or update a resource** ([`author_resource`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#author_resource)) and gives you the link to enter the key:
>
> ```text theme={null}
> Add the Exa MCP server at https://mcp.example.com/mcp. It takes the API key in the apiKey query parameter.
> ```

### See an MCP server's tools

An MCP server's **Tools** tab displays every tool discovered at Oqoqo's last check—names, descriptions, parameters, and server hints (`Read-only`, `Destructive`), along with **New** or **Updated** diffs. Oqoqo checks remote servers automatically when you save a new version, connect your account, or view **Tools** after 24 hours; local servers cannot be inspected outside a run.

> [tab] Dashboard
>
> Open the MCP server's **Tools** tab and select **Refresh** (or open **⋯ → Refresh tools** in the MCP servers list).

> [tab] CLI
>
> ```bash theme={null}
> oqoqo mcp tools refresh mcp_2e8b6f13 --wait-ms 20000 --output json
> ```
>
> See [`oqoqo mcp tools refresh`](https://docs.oqoqo.ai/cli/agents-and-models#oqoqo-mcp-tools-refresh).

> [tab] Plugin (MCP)
>
> Ask your AI assistant to refresh the server. It calls **Refresh an MCP server's tools** ([`refresh_mcp_server_tools`](https://docs.oqoqo.ai/mcp-server/agents-and-setup#refresh_mcp_server_tools)).
>
> ```text theme={null}
> Check the tools of our Docs MCP server again.
> ```

### See how runs use each tool

The **Tools** tab also aggregates tool call counts across all processed runs that included the selected version.

![Tools tab of an MCP server that reads 9 tools and 381 runs. Each tool shows its name, description, and use, for example 152 calls in 88 runs or Not called, with a Details button.](https://mintcdn.com/oqoqo/9f9lglCfJlua5HlK/images/screenshots/mcp-tools-usage-light.png?fit=max\&auto=format\&n=9f9lglCfJlua5HlK\&q=85\&s=8df61c32d430ff3aafc2334f975d7e1b)

* **N calls in R runs** (or **Not called**): total calls across runs, including failed calls and calls where an agent swapped `.` for `_` or `-`.
* **Off in N treatments**: opens **Treatments (Toolsets)** filtered to treatments that disable that tool. Runs where a tool was disabled are excluded from its active run denominator (**3 calls in 2 runs of the 4 it was on**).

> [tab] Dashboard
>
> Open the MCP server's **Tools** tab and pick any version from the version selector.

> [tab] CLI
>
> ```bash theme={null}
> oqoqo mcp tools list mcp_2e8b6f13 --output json
> ```
>
> Returns `usageRunCount`, per-tool `onRunCount`, `runCount`, `callCount`, and `offInTreatmentCount` ([`oqoqo mcp tools list`](https://docs.oqoqo.ai/cli/agents-and-models#oqoqo-mcp-tools-list)).

> [tab] Plugin (MCP)
>
> Ask your AI assistant which tools agents called; it runs **List an MCP server's tools** ([`list_mcp_server_tools`](https://docs.oqoqo.ai/mcp-server/agents-and-setup#list_mcp_server_tools)).
>
> ```text theme={null}
> Which tools of our Docs MCP server did agents call, and which treatments turn tools off?
> ```

### Test without a tool

To measure a single MCP tool's value, compare a treatment with the tool against an identical copy with that tool disabled ([change one thing at a time](https://docs.oqoqo.ai/experiments/treatments.md#change-one-thing-at-a-time)).

> [tab] Dashboard
>
> On the server's **Tools** tab, select **Details** on the tool, select **Test without this tool**, and choose a treatment that includes this server version. Oqoqo clones (or opens) the matching treatment with that tool off.

> [tab] CLI
>
> Inspect the treatment's version IDs with [`oqoqo catalog list --kind treatment --projection full`](https://docs.oqoqo.ai/cli/catalog#oqoqo-catalog-list), then create a copy via [`oqoqo resources apply`](https://docs.oqoqo.ai/cli/catalog#oqoqo-resources-apply) with `disabledMcpTools` ([Turn off MCP tools](https://docs.oqoqo.ai/experiments/treatments.md#turn-off-mcp-tools)).

> [tab] Plugin (MCP)
>
> Ask your AI assistant to create a copy without that tool; it calls [`inspect_catalog`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#inspect_catalog) and [`author_resource`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#author_resource).
>
> ```text theme={null}
> Make a copy of the "Docs MCP" treatment without the ask_question tool of our Docs MCP server.
> ```

### Saved header values and the server address

To keep secrets from being redirected to untrusted URLs, saved MCP header values and OAuth client secrets are bound only to server addresses confirmed by a person in the dashboard.

* **Saving or changing a URL in the dashboard** binds saved secrets to that address automatically (previous addresses stay bound so you can compare versions at different URLs).
* **Saving a new URL via the CLI or plugin** leaves secrets unbound until a human opens the version's **Tools** tab and selects **Refresh** (check the **Binds the saved values to …** URL first). Until then, launches stop with `mcp_header_values_unbound` and CLI/MCP refreshes fail with `mcp_tool_check_needs_web`.
* **Rotating a leaked key** binds the new key only to the current address; select **Refresh** on any older versions that should receive the new key.

## CLIs and SDKs

Open **Manage → Tools → CLIs** or **SDKs** and configure:

* **Install**: package manager + exact package or a single-line **Custom** install command (runs during image Build before variables exist).
* **Post-install commands** (CLIs only): shell commands that run after machine setup with `${NAME}` variables populated (for example, signing in).
* **Variables**: keys or tokens injected into post-install commands and the run environment. CLI/SDK variables override machine variables of the same name ([When two places set the same variable](https://docs.oqoqo.ai/experiments/machines-and-files.md#when-two-places-set-the-same-variable)).
* **Commands** (CLIs only): executable names on `PATH` that count toward **Treatment use** in [Run details](https://docs.oqoqo.ai/evaluation/traces.md). Oqoqo detects commands automatically for exact npm, crates.io, or `go install` packages. For pip, gem, apt, custom installs, and version ranges, list the executable names separated by spaces or commas.

## Import from GitHub

Import **Skills** and **Files** directly from public `github.com` repositories.

**1. Open the GitHub import**

In the add dialog, select **From GitHub**.

**2. Choose the repository**

Enter a repository name, `owner/name`, `owner/`, or paste a GitHub URL into **GitHub source** and select the match.

**3. Choose a branch, tag, or commit**

Pick a ref in **Branch, tag, or commit** (defaults to the repository's default branch), or type a commit SHA.

**4. Choose a path**

Pick a specific folder or file in **File or folder path**, or leave blank to import the entire repository.

**5. Import**

Optionally enable **Mark as official** for skills, then select **Import** to save an immutable snapshot at that commit.

Select **Check for updates** on any imported skill or file to pull newer commits (creates a new version if changed; past runs keep their snapshots). From the CLI or plugin, search public repositories with [`oqoqo github browse`](https://docs.oqoqo.ai/cli/catalog#oqoqo-github-browse) or [`browse_github_source`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#browse_github_source) and pass `source` to `resources apply` / `author_resource`.

### See where an import came from

GitHub-imported records display a GitHub link beside their title and record the **Repository**, **Branch or tag**, **Path**, and **Commit** under the info icon (`sourceAction` in [`oqoqo resources inspect`](https://docs.oqoqo.ai/cli/catalog#oqoqo-resources-inspect) and [`inspect_resource`](https://docs.oqoqo.ai/mcp-server/catalog-and-uploads#inspect_resource) with `definition` view).

## Add the values a tool needs

Tools missing required secrets show **Needs values** (or **Connect account** for OAuth MCP servers), and **Home** flags them with direct setup buttons. Secrets are entered only in the dashboard; optional empty values never block a launch.

## Official versions

Turn on **Mark as official** on a tool's page (or during skill import) to designate the canonical version of your product interface. Oqoqo maintains four read-only treatments—**All official skills**, **All official MCPs**, **All official CLIs**, and **All official SDKs**—which automatically track your official versions.

## Attach tools to a treatment

After saving a tool, select **Create treatment** or add the tool version under **Manage → Treatments (Toolsets)**. When saving a new tool version, use **Update linked treatments?** to move existing treatments to the latest version ([Keep treatments up to date](https://docs.oqoqo.ai/experiments/treatments.md#keep-treatments-up-to-date)).

## Approvals during runs

Inside cloud runs, all tool calls—including MCP tools marked `destructiveHint` or `_meta["anthropic/requiresUserInteraction"]`—are auto-approved so agents never stall. Always run tasks against test data that agents can safely modify or delete.

## Delete a tool

You cannot delete a tool version still attached to a treatment, and MCP server, CLI, or SDK versions used by past experiments cannot be deleted even after removing them from treatments.

> [!WARNING]
>
> Deleting a skill or task version permanently deletes every experiment, run, Eval, and Insight that depended on it. Always review the delete preview before confirming.

## Next steps

> [card] [MCP server sign-in](https://docs.oqoqo.ai/experiments/mcp-server-sign-in.md)
>
> Set up OAuth and custom OAuth apps for remote MCP servers.

> [card] [Treatments (Toolsets)](https://docs.oqoqo.ai/experiments/treatments.md)
>
> Group tools into treatments and isolate single changes.

> [card] [Launch an experiment](https://docs.oqoqo.ai/experiments/launch.md)
>
> Compare your treatments across tasks and agents.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.