Skip to main content
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.

​
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. Ask for an outcome, and let the agent find the tool, check the price, and use the result:
Send to your agent

​
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 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 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 covers the full runtime flow.

​
Next steps

MCP

See every kind of tool your agent can call.

Agent keys

Set per-call and per-run budgets for an unattended agent.