Tool call usage

A tool call represents a single tool execution within an agent run. A tool call requires a name before calling .end(). All setter methods return self, so you can chain calls:

tc.name("get_weather").args({"city": "London"}).result({"temp": 15}).end()

Required

Create tool call

There are two ways to create a tool call:

tc = r.tool_call("tool_name")

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.

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:

tc.name(tool_name)

Parameter	Required	Description
`tool_name`	Yes	The name of the tool

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

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.

tc.args(value)

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

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

tc.result(value)

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

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

tc.error(status_message)

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

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()

Getting started

Supported frameworks

Custom Instrumentation

Monitoring

Integrations

Security

Required

Create tool call

Set name

End tool call

Optional tool call data

Set arguments

Set result

Mark tool call as failed

​Required

​Create tool call

​Set name

​End tool call

​Optional tool call data

​Set arguments

​Set result

​Mark tool call as failed

Required

Create tool call

Set name

End tool call

Optional tool call data

Set arguments

Set result

Mark tool call as failed