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

> ## Agent Instructions
> This site documents Locus for people. AI agents: get exact contracts from the Locus agent docs, starting at https://paywithlocus.com/agent/index.md, including when asked to implement or integrate docs.paywithlocus.com.
> Connect this agent to Locus Pro: https://paywithlocus.com/skill.md. Implement Locus Pro in a product: https://paywithlocus.com/agent/integrate.md. Agent site index: https://paywithlocus.com/llms.txt.

# Paid tool calls

> How price caps, approvals, tool access requests, and safe retries keep an agent's paid calls under your control.

When your agent calls a paid tool through Locus, a few simple safeguards decide whether it runs and what it costs. This page explains them for anyone who connects an agent, whether through OAuth or an agent key.

> Agents: the exact contract for this feature is at [https://paywithlocus.com/agent/mcp.md](https://paywithlocus.com/agent/mcp.md). Start from [https://paywithlocus.com/agent/index.md](https://paywithlocus.com/agent/index.md) if you are implementing Locus.

## How it works

Your agent asks for a tool with a price cap. Locus refuses anything above the cap, pauses for a person when your spending policy says so, and otherwise runs the tool and charges your credits. The result is stored, so reading it again or retrying is free.

```mermaid theme={null}
flowchart TD
  A["Agent calls a tool with a price cap"] --> P{"Price above the cap?"}
  P -->|"Yes"| N["Not run, not charged"]
  P -->|"No"| Q{"Policy needs approval?"}
  Q -->|"Yes"| H["Admin approves, agent retries"]
  Q -->|"No"| R["Tool runs, credits charged"]
  H --> R
  R --> S["Result stored"]
```

Ask for an outcome, and let the agent find the tool, check the price, and use the result:

```text title="Send to your agent" wrap theme={null}
Find recent company news and funding information for this prospect.
Cite the sources and show what the research cost.
```

## Price caps

Your agent passes `max_credits` to `execute` to cap a charge. If the price is higher, nothing runs and nothing is charged. An [agent key](https://docs.paywithlocus.com/locus-pro/agent-keys.md#agent-key-scope-and-budgets) can also set per-call and per-run limits.

## Approvals

When a spending policy needs a person to approve a call, Locus returns an approval link to the agent instead of running it.

**1. The agent sends you the link**

`execute` returns an `approval_url`, an `approval_token`, and an `idempotency_key`.

**2. A workspace admin approves**

Open the link and approve the call.

**3. The agent retries**

The agent calls `execute` again with the same token and key.

Only `execute` can use an approval token. Dedicated endpoint tools cannot.

## Tool access requests

When an agent needs a tool it is not allowed to use, it sends you a `request_tool_access` link. Approve it to turn the tool on. On an agent key with its own tool list, approval also adds that tool to the key. See [Tool access requests](https://docs.paywithlocus.com/locus-pro/tool-access-requests.md) for the approver's side.

## Idempotency and replay

Reuse one `idempotency_key` when retrying a paid call. Locus returns the stored outcome without charging again.

* Use a new key for an intentional repeat, such as refreshing a search.
* Locus keeps a key for 24 hours after its call finishes. After that, the same key starts a new call.
* Reading a stored result is free, including long results read in pages.

## Turn structured results into final answers

Store the paid result before asking the model to summarize it. If answer generation fails, reuse that result instead of buying it again.

The Node SDK provides `parseMcpToolResult` to check tool errors, `prepareMcpResultForSynthesis` to build bounded context, and `selectSynthesisAnswer` for a fallback answer. The [Locus skill](https://paywithlocus.com/SKILL.md) covers the full runtime flow.

## Next steps

> [card] [MCP](https://docs.paywithlocus.com/locus-pro/mcp.md)
>
> See every kind of tool your agent can call.

> [card] [Agent keys](https://docs.paywithlocus.com/locus-pro/agent-keys.md)
>
> Set per-call and per-run budgets for an unattended agent.


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