.NET API
ToolInvocationRecord
Tracon.Abstractions.dllThe summary of a single completed tool call.
public sealed record ToolInvocationRecord : IEquatable<ToolInvocationRecord>- Inheritance
- object ← ToolInvocationRecord
- Implements
- IEquatable<ToolInvocationRecord>
- Inherited Members
- object.GetType(), object.ToString(), object.Equals(object?), object.Equals(object?, object?), object.ReferenceEquals(object?, object?), object.GetHashCode()
Remarks
Section titled “Remarks”This record is a projection of the event stream: the same information also exists in the RunEventType.ToolInvoking and RunEventType.ToolInvoked events. It is kept in a separate table so that ToolInvocationRecord.Duration and per-tool totals can be queried without scanning the whole event stream.
The record is written only when the call settles; its
duration is computed from correlating the ToolInvoking and
ToolInvoked event pair.
Constructors
Section titled “Constructors”ToolInvocationRecord()
Section titled “ ToolInvocationRecord()”public ToolInvocationRecord()Properties
Section titled “Properties”Arguments
Section titled “ Arguments”The call arguments. Raw text; may not be valid JSON.
public string? Arguments { get; init; }Property Value
Section titled “Property Value”AuthorizationDenied
Section titled “ AuthorizationDenied”Whether IToolAuthorizationHandler denied this call before it ran.
public bool AuthorizationDenied { get; init; }Property Value
Section titled “Property Value”Remarks
Section titled “Remarks”A denied call is not an error: ToolInvocationRecord.Error
stays empty and Result carries the denial text the model
saw. This field is the only way to tell “the model chose not to call
it” apart from “the caller was not allowed to call it” when reading
the record back.
CreatedAt
Section titled “ CreatedAt”The moment the call settled (UTC).
public required DateTimeOffset CreatedAt { get; init; }Property Value
Section titled “Property Value”Duration
Section titled “ Duration”The call’s duration. null if the event pair did not match.
public TimeSpan? Duration { get; init; }Property Value
Section titled “Property Value”The error message. Populated only if the call errored.
public string? Error { get; init; }Property Value
Section titled “Property Value”The record identifier. A time-ordered UUID (v7).
public required Guid Id { get; init; }Property Value
Section titled “Property Value”LateCompletedAt
Section titled “ LateCompletedAt”The moment a call that had already been reported as timed out actually settled (UTC). null for every call that settled within its own timeout.
public DateTimeOffset? LateCompletedAt { get; init; }Property Value
Section titled “Property Value”Remarks
Section titled “Remarks”A timeout stops the wait. A tool body that does not honour the cancellation it is then handed keeps running, and it can still succeed and still spend real money. When it does, ToolInvocationRecord.Result, ToolInvocationRecord.Usage and ToolInvocationRecord.Duration are filled in on this same row and this field records when that happened.
ToolInvocationRecord.TimedOut stays true and ToolInvocationRecord.Error keeps the timeout message: both describe what the MODEL was told, which does not change after the fact. This field is what distinguishes “it timed out and was never heard from again” from “it timed out and then finished anyway”.
Result
Section titled “ Result”The call result. Raw text; may not be valid JSON.
public string? Result { get; init; }Property Value
Section titled “Property Value”The run that made the call.
public required Guid RunId { get; init; }Property Value
Section titled “Property Value”Source
Section titled “ Source”The tool’s source. null for tools defined in code; the server name for MCP tools.
public string? Source { get; init; }Property Value
Section titled “Property Value”Succeeded
Section titled “ Succeeded”Whether the call finished successfully.
public bool Succeeded { get; }Property Value
Section titled “Property Value”TenantId
Section titled “ TenantId”The EXPECTED tenant of the run that made the call. Defense in depth; if null, no tenant check is performed.
[JsonIgnore]public string? TenantId { get; init; }Property Value
Section titled “Property Value”Remarks
Section titled “Remarks”See TenantId for the reason and why the ambient tenant is not used.
This field is WRITE-SIDE ONLY: it is not written to a column, it is only used as
the write’s WHERE guard. It would always be null when
read back, so it is excluded from the HTTP contract with Serialization.JsonIgnoreAttribute. Otherwise the OpenAPI document would declare a
field that never gets populated.
TimedOut
Section titled “ TimedOut”Whether the call ended because its execution timeout elapsed (TraconToolTimeoutException).
public bool TimedOut { get; init; }Property Value
Section titled “Property Value”ToolCallId
Section titled “ ToolCallId”The call identifier generated by the model. Distinguishes multiple calls of the same kind.
public string? ToolCallId { get; init; }Property Value
Section titled “Property Value”ToolName
Section titled “ ToolName”The name of the tool called.
public required string ToolName { get; init; }Property Value
Section titled “Property Value”The call’s non-token measurement and cost. null if the tool reported no measurement — which is empty for the vast majority of calls.
public ToolCallUsage? Usage { get; init; }Property Value
Section titled “Property Value”Remarks
Section titled “Remarks”The value is reported by the tool’s own body with
TraconToolUsage.Report(...) and linked to this record by the
call identifier.
Methods
Section titled “Methods”Equals(object?)
Section titled “ Equals(object?)”public override bool Equals(object? obj)Parameters
Section titled “Parameters”obj object?
Returns
Section titled “Returns”Equals(ToolInvocationRecord?)
Section titled “ Equals(ToolInvocationRecord?)”public bool Equals(ToolInvocationRecord? other)Parameters
Section titled “Parameters”other ToolInvocationRecord?
Returns
Section titled “Returns”GetHashCode()
Section titled “ GetHashCode()”public override int GetHashCode()Returns
Section titled “Returns”ToString()
Section titled “ ToString()”public override string ToString()Returns
Section titled “Returns”Operators
Section titled “Operators”operator ==(ToolInvocationRecord?, ToolInvocationRecord?)
Section titled “ operator ==(ToolInvocationRecord?, ToolInvocationRecord?)”public static bool operator ==(ToolInvocationRecord? left, ToolInvocationRecord? right)Parameters
Section titled “Parameters”left ToolInvocationRecord?
right ToolInvocationRecord?
Returns
Section titled “Returns”operator !=(ToolInvocationRecord?, ToolInvocationRecord?)
Section titled “ operator !=(ToolInvocationRecord?, ToolInvocationRecord?)”public static bool operator !=(ToolInvocationRecord? left, ToolInvocationRecord? right)Parameters
Section titled “Parameters”left ToolInvocationRecord?
right ToolInvocationRecord?