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

# Add it as a tool

> One tool in the model loop you already run.

If your agent already runs a model against a tools array, the integration is two calls. `payman.tool()` puts the served definition in the array; `handleToolUse()` runs the action when the model calls it.

```ts Node theme={null}
import Anthropic from "@anthropic-ai/sdk";
import { PaymanConnect } from "@paymanai/connect";

const anthropic = new Anthropic();
const payman = new PaymanConnect();

const reply = await anthropic.messages.create({
  model: "claude-opus-5",
  max_tokens: 16000,
  tools: [payman.tool()],          // sync, no await
  messages,
});

messages.push({ role: "assistant", content: reply.content });

for (const block of reply.content) {
  if (block.type === "tool_use" && block.name === "payman_money_task") {
    const turn = await payman.forUser(userId).handleToolUse(
      { id: block.id, input: block.input },
      { onEvent: (e) => e.type === "progress" && show(e.progress.label) },
    );
    messages.push({ role: "user", content: [turn.toolResult] });  // model-visible
    render(turn.ui);                                              // app-visible
  }
}
```

## The two calls

`payman.tool()` is synchronous. It returns the definition the platform serves: name `payman_money_task`, one input field, `instruction`. Never transcribe the definition into your code; the SDK caches the served copy and ships a bundled snapshot for the first call.

`payman.toolDefinitionVersion()` names the contract date you are running against, and `await payman.doctor()` reports drift.

`handleToolUse()` takes the block's `id` and `input`, runs the action, and resolves a `ToolTurn` with two fields:

| Field        | Who reads it | What it carries                                                                                                      |
| ------------ | ------------ | -------------------------------------------------------------------------------------------------------------------- |
| `toolResult` | The model    | A ready `tool_result` block: a JSON status envelope carrying `status` and guidance, plus the answer text on success. |
| `ui`         | Your app     | The full result, the same four kinds `run()` returns: `ok`, `needs_connection`, `approval`, `error`.                 |

Push `toolResult` back to the model unchanged. Render from `ui`: switch on `kind` and show the connect or [approval button](/build/approvals) exactly as you would after `run()`. `toolResult` structurally cannot carry `connectUrl`, `approvalUrl`, or a ref; URLs exist only on `ui`.

## Progress while it runs

`handleToolUse()` accepts the same options as `run()`. Passing `onEvent` switches the call to the streaming route and delivers frames while the result is still pending.

Each progress frame carries a `phase` (`started`, `completed`, `waiting`) and a `label` written for the customer. Render the label and replace it on the next frame rather than stacking lines.

## One string in

The schema has one field and nothing else: no amount, no payee, no credential, no session id. Pass the customer's request as `instruction` and the platform parses it.

Do not rule requests out by institution type in your prompt. Capability varies with the customer's own agent behind the connection, so call the tool and let the result answer. The served description already carries the ground rules for relaying and attributing answers, so they arrive with the tool rather than depending on your prompt.