# MCP tools

> The nine tools your AI gets, which ones are free and how agents use them.

Once connected, your AI gets nine Frames tools. Searching the catalog and checking your account are free. Only two tools spend credits: pulling data from paid tools, and handing a whole task to Frames F1.

## The nine tools

| Tool | What it does | Cost | Inputs |
| --- | --- | --- | --- |
| `frames_search_tools` | Searches the catalog from a description of what you need. The best matches come back ready to call, with a live check, a price and the exact inputs. | Free | `queries` (up to 4 phrasings) or `query`; optional `capability` |
| `frames_get_tool` | Shows the full details of one tool | Free | `id` |
| `frames_probe_tools` | Checks up to 5 tools at once: whether they're up, their price and their exact inputs | Free, with an hourly limit | `ids` |
| `frames_invoke_tools` | Calls up to 10 tools in one request, in parallel. Each call is checked, and calls that don't deliver are refunded. | Paid: data cost plus 15% | `calls` (each an `id` and `args`); optional `max_usd`, `idempotency_key`, `objective`, `search_ids` |
| `frames_run_capability` | Hands a whole task to Frames F1, which plans, buys data, checks it and answers | Paid: F1 pricing | `task`; optional `max_usd`, `output_schema` |
| `frames_get_run` | Fetches a run's status, result, billing and receipts | Free | `run_id` |
| `frames_get_receipt` | Shows the receipts for one run and what it was billed | Free | `run_id` |
| `frames_get_tool_results` | Reads the full response of a call from a past run, including responses too large to return inline | Free | `run_id`; optional `seq` |
| `frames_get_usage` | Shows your credit balance, what's left of your monthly credits and your per-run cap | Free | None |

## Two ways an agent uses Frames

### Pull data directly

This is the cheapest way. The agent searches, probes only if a match isn't ready to call, then invokes. It writes the calls itself and pays for delivered data plus 15%.

### Hand off the whole task

The agent calls `frames_run_capability`. Frames F1 does the research and returns a finished answer with receipts. It costs more, because F1's own model work is billed too. See [Frames F1](https://frames.ag/docs/f1.md).

## Good to know

- **Spending caps.** Paid tools run on your plan's per-run cap. `max_usd` can only set it lower.
- **Long runs.** If a run outlasts the request, the tool returns `status: "running"` and a `run_id`. Call `frames_get_run` until the status is `completed` or `failed`.
- **Reporting cost.** Every paid result has a `billing` block with the credits charged, capped at the run's budget, and the balance left. Agents should report `billing.charged_credits`, not the dollar figures in `usage`.
- **Retries.** Pass the same `idempotency_key` when retrying `frames_invoke_tools`, and the batch is never paid twice.
- **Search IDs.** Passing the `search_id` from a search into the invoke call helps Frames rank tools better for everyone.

The same search and invoke calls are also plain HTTP endpoints, for agents that don't speak MCP. See [Tool endpoints](https://frames.ag/docs/tool-endpoints.md).