Skip to content

ToolResult TValue,TError

NexusLabs.Needlr.AgentFramework

NexusLabs.Needlr.AgentFramework.Tools

ToolResult<TValue,TError> Struct

Standard return type for [AgentFunction] methods providing two separate channels: one for the LLM (structured JSON, never a raw stack trace) and one for C# (full exception context and retry signal).

public readonly struct ToolResult<TValue,TError> : NexusLabs.Needlr.AgentFramework.Tools.IToolResult
    where TError : class

Type parameters

TValue

The success value type. Serialised to JSON for the LLM on success.

TError

The structured error shape. Serialised as { "error": … } for the LLM on failure. Must be a reference type so null can represent the absence of an error.

Implements IToolResult

Properties

ToolResult<TValue,TError>.Error Property

Gets the structured error payload. null on success.

public TError? Error { get; }

Property Value

TError

ToolResult<TValue,TError>.Exception Property

Gets the original unhandled Exception, if any. \<strong>Never sent to the LLM.\</strong> Preserved for diagnostics and resilience decisions.

public System.Exception? Exception { get; }

Implements Exception

Property Value

System.Exception

ToolResult<TValue,TError>.IsSuccess Property

Gets a value indicating whether the tool call succeeded.

public bool IsSuccess { get; }

Implements IsSuccess

Property Value

System.Boolean

ToolResult<TValue,TError>.IsTransient Property

Indicates whether the failure is transient and suitable for retry. true = retry, false = don't retry, null = let the resilience layer decide via its own heuristics.

public System.Nullable<bool> IsTransient { get; }

Implements IsTransient

Property Value

System.Nullable<System.Boolean>

ToolResult<TValue,TError>.Value Property

Gets the success value. default on failure.

public TValue? Value { get; }

Property Value

TValue

Methods

ToolResult<TValue,TError>.Fail(TError, Exception, Nullable<bool>) Method

Creates a failure result with a structured error payload.

public static NexusLabs.Needlr.AgentFramework.Tools.ToolResult<TValue,TError> Fail(TError error, System.Exception? exception=null, System.Nullable<bool> isTransient=null);

Parameters

error TError

Structured error sent to the LLM.

exception System.Exception

Original exception, preserved for diagnostics (never sent to LLM).

isTransient System.Nullable<System.Boolean>

Whether the failure is transient. null lets the resilience layer decide.

Returns

NexusLabs.Needlr.AgentFramework.Tools.ToolResult<TValue,TError>

ToolResult<TValue,TError>.Ok(TValue) Method

Creates a successful result wrapping value.

public static NexusLabs.Needlr.AgentFramework.Tools.ToolResult<TValue,TError> Ok(TValue value);

Parameters

value TValue

Returns

NexusLabs.Needlr.AgentFramework.Tools.ToolResult<TValue,TError>