> ## 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 Python

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 `self`, so you can chain calls:

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

## Required

### Create tool call

There are two ways to create a tool call:

```python theme={null}
tc = r.tool_call("tool_name")
```

```python theme={null}
tc = tcc.tool_call(run_id=r.run_id, tool_name="tool_name")
```

| Parameter      | Required | Description                                                              |
| -------------- | -------- | ------------------------------------------------------------------------ |
| `tool_name`    | No       | The name of the tool (can be set later with `.name()`)                   |
| `tool_call_id` | No       | Custom tool call ID. If not provided, a UUID is automatically generated. |

```python theme={null}
import contextcompany as tcc

r = tcc.run()

# Option 1: Create a tool call from a run
tc = r.tool_call("get_weather")

# Option 2: Create a tool call directly with a run ID
tc = tcc.tool_call(run_id=r.run_id, tool_name="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:

```python theme={null}
tc.name(tool_name)
```

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

```python 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()`.

```python theme={null}
tc = r.tool_call("get_weather")
tc.args({"city": "London"})

# --- Your tool execution ---
result = get_weather("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 a dictionary is provided.

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

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

```python theme={null}
# As a dictionary (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 a dictionary is provided.

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

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

```python theme={null}
# As a dictionary (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.

```python theme={null}
tc.error(status_message)
```

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

```python theme={null}
import contextcompany as tcc

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

tc = r.tool_call("get_weather")
tc.args({"city": "London"})

try:
    result = get_weather("London")
    tc.result(result)
    tc.end()
except Exception as e:
    tc.error(str(e))

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