# Paid tools

How an agent finds a pay-per-use tool, sees what it costs, runs it with a ceiling and reads the result. What the service is and what it costs is on [Services](/services).

## Before you start

- The tools come from one provider, Monid, on STACK's key. You connect nothing.
- Runs are paid from your credit at Monid's price plus its 5% processing fee: see Prepaid credit.
- Only the account's own agent finds and runs tools, with its Passport.

## Find a tool

```text
Find a tool that can look up a company's registered address.
```

The client calls `stack_discover_account_tools`, then `stack_inspect_account_tool` for the one it picks. From code or the terminal:

```typescript
const tools = stack.accounts.tools;

const found = await tools.discover('acct_123', { query: 'company registered address', limit: 5 }, { passportToken });
const info = await tools.inspect('acct_123', { provider, endpoint }, { passportToken });
// info: the input the tool takes, its price and how it is billed
```

```bash
npx @getstackrun/cli account tools acct_123 discover --query "company registered address"
```

Finding and inspecting are free.

## Run it

```typescript
const run = await tools.run('acct_123', {
  provider,
  endpoint,
  input,              // the fields inspect listed
  max_results: 20,
  max_cost_cents: 50,
}, { passportToken });
// run.id, run.state, run.charged_cents, run.result, run.files
```

- The tool is stack_run_account_tool. From the terminal: account tools \<id> run, with --input or --input-file.
- Some tools charge by the call and some by the result. max_results (1 to 1,000) limits how many results a run can return.
- Before the run, STACK holds the most it could cost. max_cost_cents lowers that hold.
- Where a tool gives no way to bound a run, the hold is an estimate, and the run shows price_type ESTIMATED.
- Afterwards the run is charged Monid's price plus its 5% processing fee. A cost above the hold is taken from credit.
- The input is at most 64 KB.

## Read the result

- A run that is still pending has no final charge yet. Read it again by its id: stack_get_account_tool_run.
- Files a run makes are saved to the agent's drive. Each entry in files carries the drive file id.
- A result is not stored. Reading a run again fetches it again from the provider.
- There is no list of past runs. Keep the run id.

Results come from the web and from third parties. They are scanned and flagged on every account. With controls on, a flagged result is withheld, and the run says so.

## What counts as an action

A run is one action. Finding, inspecting and reading a run are free. Monid's price plus its 5% processing fee is charged from credit, with no fee from STACK.

## When a run is refused

- 400 VALIDATION_ERROR - max_results is outside 1 to 1,000, or the input is over 64 KB.
- 422 TOOL_PRICE_REFUSED - the input is nested too deeply, or the tool cannot be priced. Nothing was held.
- 404 NOT_FOUND - the provider does not list that tool.
- 400 TOOL_RUN_REJECTED - the provider refused the input. Nothing was charged.
- 503 TOOLS_UNAVAILABLE - the provider cannot be reached. Nothing was charged.
- 402 INSUFFICIENT_BALANCE or AGENT_BUDGET_EXCEEDED - the credit cannot cover the hold, or the agent has a budget that cannot.
- 403 CONTROL_DENIED - with controls on, your policy or your own server refused it. Controls are asked as tool.run, with the tool and the amount held. A policy can list the tools allowed.

## Reference

Every field is on [Models and Paid Tools](/docs/api/account-models-tools). Every tool is in the [tool reference](/docs/mcp-tools).
