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

# Tool call usage

> Using tool calls with The Context Company custom instrumentation for TypeScript

A [tool call](/concepts#tool-calls) represents a single tool execution within an [agent run](/concepts#agent-runs). A tool call requires a **name** before calling `.end()`.

All setter methods return `this`, so you can chain calls:

```typescript theme={null}
tc.name("get_weather").args({ city: "London" }).result({ temp: 15 }).end();
```

## Required

### Create tool call

Create a tool call from a run:

```typescript theme={null}
const tc = r.toolCall("tool_name");
```

| Parameter | Required | Description          |
| --------- | -------- | -------------------- |
| `name`    | **Yes**  | The name of the tool |

```typescript theme={null}
import { run } from "@contextcompany/custom";

const r = run();
const tc = r.toolCall("get_weather");
```

### Set name

The name is **required** before calling `.end()`. If you didn't provide it when creating the tool call, set it with:

```typescript theme={null}
tc.name(toolName);
```

| Parameter  | Required | Description          |
| ---------- | -------- | -------------------- |
| `toolName` | **Yes**  | The name of the tool |

```typescript theme={null}
tc.name("get_weather");
```

### End tool call

End the tool call. A tool call must have a **name** set before calling `.end()`. The tool call cannot be modified after calling `.end()`.

```typescript theme={null}
const tc = r.toolCall("get_weather");
tc.args({ city: "London" });

// --- Your tool execution ---
const result = await getWeather("London");
// --- End of tool execution ---

tc.result(result);
tc.end();
```

***

## Optional tool call data

### Set arguments

Set the arguments passed to the tool. Values are automatically serialized to JSON if an object is provided.

```typescript theme={null}
tc.args(value);
```

| Parameter | Required | Description                                     |
| --------- | -------- | ----------------------------------------------- |
| `value`   | **Yes**  | Arguments passed to the tool (string or object) |

```typescript theme={null}
// As an object (auto-serialized)
tc.args({ city: "London", unit: "celsius" });

// As a string
tc.args('{"city": "London", "unit": "celsius"}');
```

### Set result

Set the result returned by the tool. Values are automatically serialized to JSON if an object is provided.

```typescript theme={null}
tc.result(value);
```

| Parameter | Required | Description                                    |
| --------- | -------- | ---------------------------------------------- |
| `value`   | **Yes**  | Result returned by the tool (string or object) |

```typescript theme={null}
// As an object (auto-serialized)
tc.result({ temp: 15, unit: "C", condition: "cloudy" });

// As a string
tc.result('{"temp": 15, "unit": "C", "condition": "cloudy"}');
```

### Mark tool call as failed

Sets the status code to error. The tool call cannot be modified after calling `.error()`. Unlike `.end()`, calling `.error()` does not require a name to be set.

```typescript theme={null}
tc.error(statusMessage?);
```

| Parameter       | Required | Description                |
| --------------- | -------- | -------------------------- |
| `statusMessage` | No       | A description of the error |

```typescript theme={null}
import { run } from "@contextcompany/custom";

const r = run();
r.prompt("What is the weather in London?");

const tc = r.toolCall("get_weather");
tc.args({ city: "London" });

try {
  const result = await getWeather("London");
  tc.result(result);
  tc.end();
} catch (e) {
  tc.error(String(e));
}

// Run still ends successfully even if a tool call fails
await r.end();
```

***

## Factory pattern

If you have all tool call data available upfront, use the `sendToolCall` function:

```typescript theme={null}
import { sendToolCall } from "@contextcompany/custom";

await sendToolCall({
  runId: "run_abc",
  name: "search",
  args: { query: "SF weather" },
  result: { temp: 72 },
  startTime: new Date(),
  endTime: new Date(),
});
```