Skip to content

ToolCallDiagnostics

NexusLabs.Needlr.AgentFramework

NexusLabs.Needlr.AgentFramework.Diagnostics

ToolCallDiagnostics Class

Diagnostics for a single tool/function invocation within an agent run.

public sealed record ToolCallDiagnostics : System.IEquatable<NexusLabs.Needlr.AgentFramework.Diagnostics.ToolCallDiagnostics>

Inheritance System.Object 🡒 ToolCallDiagnostics

Implements System.IEquatable<ToolCallDiagnostics>

Example

foreach (var tool in diagnostics.ToolCalls)
{
    Console.WriteLine($"{tool.ToolName}: {tool.Duration.TotalMilliseconds}ms " +
        $"({(tool.Succeeded ? "ok" : tool.ErrorMessage)})");
    if (tool.CustomMetrics is { Count: > 0 })
        foreach (var (k, v) in tool.CustomMetrics)
            Console.WriteLine($"  {k} = {v}");
}

Remarks

Tool calls are captured by the diagnostics function-calling middleware and ordered by their Sequence number, which is reserved before the call begins. This ensures parallel tool calls are ordered by invocation time, not completion time.

Custom metrics (e.g., cache hit/miss, provider name, byte counts) can be attached via AttachMetric(string, object) during tool execution.

Constructors

ToolCallDiagnostics(int, string, TimeSpan, bool, string, DateTimeOffset, DateTimeOffset, IReadOnlyDictionary<string,object>) Constructor

Diagnostics for a single tool/function invocation within an agent run.

public ToolCallDiagnostics(int Sequence, string ToolName, System.TimeSpan Duration, bool Succeeded, string? ErrorMessage, System.DateTimeOffset StartedAt, System.DateTimeOffset CompletedAt, System.Collections.Generic.IReadOnlyDictionary<string,object?>? CustomMetrics);

Parameters

Sequence System.Int32

Zero-based invocation order within the agent run. Reserved before async execution begins.

ToolName System.String

The name of the tool/function that was called (e.g., "ReadFile", "WebSearch").

Duration System.TimeSpan

Wall-clock time for the tool execution.

Succeeded System.Boolean

Whether the tool returned a result without throwing.

ErrorMessage System.String

The exception message if the tool threw; null on success.

StartedAt System.DateTimeOffset

UTC timestamp when the tool invocation began.

CompletedAt System.DateTimeOffset

UTC timestamp when the tool invocation finished.

CustomMetrics System.Collections.Generic.IReadOnlyDictionary<System.String,System.Object>

Arbitrary key-value pairs attached by the tool implementation via IToolMetricsAccessor. null if no metrics were recorded.

Example

foreach (var tool in diagnostics.ToolCalls)
{
    Console.WriteLine($"{tool.ToolName}: {tool.Duration.TotalMilliseconds}ms " +
        $"({(tool.Succeeded ? "ok" : tool.ErrorMessage)})");
    if (tool.CustomMetrics is { Count: > 0 })
        foreach (var (k, v) in tool.CustomMetrics)
            Console.WriteLine($"  {k} = {v}");
}

Remarks

Tool calls are captured by the diagnostics function-calling middleware and ordered by their Sequence number, which is reserved before the call begins. This ensures parallel tool calls are ordered by invocation time, not completion time.

Custom metrics (e.g., cache hit/miss, provider name, byte counts) can be attached via AttachMetric(string, object) during tool execution.

Properties

ToolCallDiagnostics.AgentName Property

The name of the agent that triggered this tool call, or null if the agent name was not available. Used to attribute tool calls to the correct agent in multi-agent workflows where diagnostics are aggregated.

public string? AgentName { get; init; }

Property Value

System.String

ToolCallDiagnostics.Arguments Property

The arguments passed to the tool invocation, keyed by parameter name. null if the tool took no arguments or capture was unavailable. Captured losslessly to enable post-hoc replay and tool-call-accuracy evaluation.

public System.Collections.Generic.IReadOnlyDictionary<string,object?>? Arguments { get; init; }

Property Value

System.Collections.Generic.IReadOnlyDictionary<System.String,System.Object>

ToolCallDiagnostics.ArgumentsCharCount Property

Character count of the JSON-serialized representation of Arguments. 0 when arguments are absent or serialization failed. Useful for detecting unexpectedly large tool argument payloads.

public long ArgumentsCharCount { get; init; }

Property Value

System.Int64

ToolCallDiagnostics.CompletedAt Property

UTC timestamp when the tool invocation finished.

public System.DateTimeOffset CompletedAt { get; init; }

Property Value

System.DateTimeOffset

ToolCallDiagnostics.CustomMetrics Property

Arbitrary key-value pairs attached by the tool implementation via IToolMetricsAccessor. null if no metrics were recorded.

public System.Collections.Generic.IReadOnlyDictionary<string,object?>? CustomMetrics { get; init; }

Property Value

System.Collections.Generic.IReadOnlyDictionary<System.String,System.Object>

ToolCallDiagnostics.Duration Property

Wall-clock time for the tool execution.

public System.TimeSpan Duration { get; init; }

Property Value

System.TimeSpan

ToolCallDiagnostics.ErrorMessage Property

The exception message if the tool threw; null on success.

public string? ErrorMessage { get; init; }

Property Value

System.String

ToolCallDiagnostics.Result Property

The value returned by the tool invocation, or null if the tool returned null or the call failed. Captured losslessly (the actual object returned, not a serialized form) to enable post-hoc evaluation and replay.

public object? Result { get; init; }

Property Value

System.Object

ToolCallDiagnostics.ResultCharCount Property

Character count of the JSON-serialized representation of Result. 0 when the result is absent or serialization failed. Useful for detecting tool responses that bloat the chat window.

public long ResultCharCount { get; init; }

Property Value

System.Int64

ToolCallDiagnostics.Sequence Property

Zero-based invocation order within the agent run. Reserved before async execution begins.

public int Sequence { get; init; }

Property Value

System.Int32

ToolCallDiagnostics.StartedAt Property

UTC timestamp when the tool invocation began.

public System.DateTimeOffset StartedAt { get; init; }

Property Value

System.DateTimeOffset

ToolCallDiagnostics.Succeeded Property

Whether the tool returned a result without throwing.

public bool Succeeded { get; init; }

Property Value

System.Boolean

ToolCallDiagnostics.ToolName Property

The name of the tool/function that was called (e.g., "ReadFile", "WebSearch").

public string ToolName { get; init; }

Property Value

System.String