Skip to main content
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 this, so you can chain calls: 
tc.name("get_weather").args({ city: "London" }).result({ temp: 15 }).end();

​
Required

​
Create tool call

Create a tool call from a run: 
const tc = r.toolCall("tool_name");
ParameterRequiredDescription
nameYesThe name of the tool
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: 
tc.name(toolName);
ParameterRequiredDescription
toolNameYesThe 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(). 
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. 
tc.args(value);
ParameterRequiredDescription
valueYesArguments passed to the tool (string or object)
// 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. 
tc.result(value);
ParameterRequiredDescription
valueYesResult returned by the tool (string or object)
// 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. 
tc.error(statusMessage?);
ParameterRequiredDescription
statusMessageNoA description of the error
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: 
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(),
});