TraconToolRegistration

Namespace Tracon · Assembly Tracon.Abstractions.dll

A single tool registered with dependency injection. Tracon builds the tool registry from these registrations.

public sealed class TraconToolRegistration

Inheritance

object ← TraconToolRegistration

Inherited Members

object.GetType(), object.ToString(), object.Equals(object?), object.Equals(object?, object?), object.ReferenceEquals(object?, object?), object.GetHashCode()

Remarks

The consumer can also register tools from their own DI modules. Only the tool itself is required; every other setting is an init property that keeps its default when it is not set.

A registration is shared by every run, so it cannot change after it is created.

builder.Services.AddSingleton(new TraconToolRegistration(refundTool)
{
    RequiresApproval = true,
    Effect = ToolEffect.Write,
});

Constructors

TraconToolRegistration(AIFunctionDeclaration)

Creates a new tool registration with default settings.

public TraconToolRegistration(AIFunctionDeclaration function)

Parameters

function AIFunctionDeclaration

The tool to register. An AI.AIFunction runs on the server; an AI.AIFunctionDeclaration that is not an AI.AIFunction (declaration-only, produced by AddClientTool) runs on the caller instead.

Exceptions

ArgumentNullException

function is null.

TraconException

The tool name does not follow the tool naming rules.

Properties

Effect

The tool’s effect class. Defaults to ToolEffect.Read.

public ToolEffect Effect { get; init; }

Property Value

ToolEffect

Function

The registered tool.

public AIFunctionDeclaration Function { get; }

Property Value

AIFunctionDeclaration

MaxOutputBytes

The most bytes (UTF-8) this tool’s result may carry, or null to use the installation default. A result over the limit is trimmed and handed to the model inside an envelope that states how many bytes were dropped.

public int? MaxOutputBytes { get; init; }

Property Value

int?

Remarks

Bounding the output inside the tool’s own body is always better: the tool knows its data, this only counts bytes. This limit is the last defence for the day that bound is forgotten.

RequiredPermission

The permission name a caller must hold to call this tool, or null when the tool declares none.

public string? RequiredPermission { get; init; }

Property Value

string?

RequiresApproval

Whether explicit approval is required before the call. Defaults to false.

public bool RequiresApproval { get; init; }

Property Value

bool

Remarks

TraconToolRegistration.Function must be an AI.AIFunction when this is true: approval defers a server-side call, and a client-side tool has no server-side body to approve.

SafeToRepeat

Whether this tool’s call may run again when an interrupted run is continued. Defaults to false.

public bool SafeToRepeat { get; init; }

Property Value

bool

Remarks

The default, false, is safe for every tool: a call this repository has no record of finishing is never repeated automatically. Continuation asks a stronger question than idempotency — not just “does the same call produce the same result?” but “may this call’s SIDE EFFECT legitimately happen a second time?” Only a tool whose author can answer yes to that should set this to true (typically by carrying its own idempotency key).

Only consulted for ToolEffect.Destructive and ToolEffect.External tools, which are otherwise refused for a continuation — setting this to true is how a tool author opts a specific irreversible or externally visible call back in. ToolEffect.Read and ToolEffect.Write calls are always safe to continue and never consult this flag.

Source

The tool’s source. null for tools defined in code; the server name for tools coming from a remote MCP server.

public string? Source { get; init; }

Property Value

string?

Timeout

The longest duration this tool’s call may run, or null to use the installation default.

public TimeSpan? Timeout { get; init; }

Property Value

TimeSpan?