# Tools for models (TypeScript)

Give Sailfork operations to Claude or an OpenAI model as tools with anthropicTools, openaiTools and run, with a complete tool-use loop for each.

`sailfork/tools` turns the operations into tool definitions and runs the one the model picks. This page has the exports, how tool names and inputs map to methods, and a loop for each provider.

## Tools for a model

`sailfork/tools` turns the operations into tool definitions for a model and runs the one the model picks.

| Export | What it is |
| --- | --- |
| `anthropicTools` | `AnthropicTool[]`: `{ name, description, input_schema }`, for the Anthropic Messages API |
| `openaiTools` | `OpenAITool[]`: `{ type: 'function', function: { name, description, parameters } }`, for the OpenAI API |
| `run(name, input, client?, options?)` | Calls the operation behind the tool `name` with the model's `input` and resolves to the answer. It uses `client`, else one built from the environment, and takes `RequestOptions` as `options` |

The tool names are the [MCP server](https://sailfork.com/docs/mcp)'s: `caisson_ship`, `issue_start`, `pull_merge`, `ci_failures`. There is one per operation of the toolsets `caissons`, `issues`, `pulls`, `ci`, `repos` and `context`, plus `wait`. The definitions come from the same catalog, so a tool and the method of the same operation do the same thing. [SDK reference](https://sailfork.com/docs/sdk-reference) lists every operation.

A tool's input is a JSON object with snake_case keys, as in `save_on_failure` or `stop_forks`. `run` maps those top-level keys to the SDK's camel case and passes nested objects through. Every tool except `wait` names the repository's owner `org`, as the MCP server does (`org`, `repo` and `number` for `pull_get`), so give the model the schema and let it fill them in. An operation that can be held answers with the `Result` object from [Writes held for a person](https://sailfork.com/docs/sdk-typescript-held-and-waits#writes-held-for-a-person), as JSON: the model sees `{ "status": "held", ... }` and can tell the user.

### With the Anthropic SDK

```ts
import Anthropic from '@anthropic-ai/sdk';
import Sailfork from 'sailfork';
import { anthropicTools, run } from 'sailfork/tools';

const anthropic = new Anthropic();
const sf = new Sailfork();

const messages: Anthropic.MessageParam[] = [
	{ role: 'user', content: 'List the open pull requests of acme/api and say which one has failing checks.' },
];

for (;;) {
	const response = await anthropic.messages.create({
		model: 'claude-sonnet-5-5',
		max_tokens: 4096,
		tools: anthropicTools,
		messages,
	});
	messages.push({ role: 'assistant', content: response.content });
	if (response.stop_reason !== 'tool_use') {
		for (const block of response.content) if (block.type === 'text') console.log(block.text);
		break;
	}

	const results: Anthropic.ToolResultBlockParam[] = [];
	for (const block of response.content) {
		if (block.type !== 'tool_use') continue;
		try {
			const answer = await run(block.name, block.input as Record<string, unknown>, sf);
			results.push({ type: 'tool_result', tool_use_id: block.id, content: JSON.stringify(answer) });
		} catch (error) {
			results.push({ type: 'tool_result', tool_use_id: block.id, content: String(error), is_error: true });
		}
	}
	messages.push({ role: 'user', content: results });
}
```

### With the OpenAI SDK

```ts
import OpenAI from 'openai';
import Sailfork from 'sailfork';
import { openaiTools, run } from 'sailfork/tools';

const openai = new OpenAI();
const sf = new Sailfork();

const messages: OpenAI.Chat.ChatCompletionMessageParam[] = [
	{ role: 'user', content: 'List the open pull requests of acme/api and say which one has failing checks.' },
];

for (;;) {
	const completion = await openai.chat.completions.create({
		model: 'gpt-4.1',
		tools: openaiTools,
		messages,
	});
	const message = completion.choices[0]!.message;
	messages.push(message);
	if (message.tool_calls === undefined || message.tool_calls.length === 0) {
		console.log(message.content);
		break;
	}

	for (const call of message.tool_calls) {
		if (call.type !== 'function') continue;
		try {
			const input = JSON.parse(call.function.arguments) as Record<string, unknown>;
			const answer = await run(call.function.name, input, sf);
			messages.push({ role: 'tool', tool_call_id: call.id, content: JSON.stringify(answer) });
		} catch (error) {
			messages.push({ role: 'tool', tool_call_id: call.id, content: String(error) });
		}
	}
}
```

Pass your client as the third argument. Without it, `run` builds its own client from the environment on first use. `sailfork/tools` shares its core with `sailfork`, so `instanceof NotFoundError` with the class imported from `sailfork` holds for errors from either entry point.

### Waiting from a tool

The `wait` tool takes `owner` inside `target`, not `org`: that is the `/api/waits` body shape, which `sf.wait`, the CLI and the MCP server all use. It takes `target` (`{ kind, owner, ... }`, as for [`sf.wait`](https://sailfork.com/docs/sdk-typescript-held-and-waits#wait-for-something-to-happen)), `until`, `timeout`, `waited` and `baseline`. It is the catalog's single window of about 55 seconds, so a long wait is several calls. When it answers `pending`, the model calls it again with the `baseline` and `waited` from that answer. `sf.wait` in your own code does that loop for you.

The same topic for Python: [Python tools for models](https://sailfork.com/docs/sdk-python-tools).

---

Every docs page: https://sailfork.com/llms.txt
