TraconToolAttribute

Namespace Tracon · Assembly Tracon.Abstractions.dll

Marks a method as a tool. AddToolsFrom<T> registers only methods carrying this attribute.

[AttributeUsage(AttributeTargets.Method, AllowMultiple = false, Inherited = false)]
public sealed class TraconToolAttribute : Attribute

Inheritance

object ← Attribute ← TraconToolAttribute

Inherited Members

Attribute.GetCustomAttributes(MemberInfo, Type), Attribute.GetCustomAttributes(MemberInfo, Type, bool), Attribute.GetCustomAttributes(MemberInfo), Attribute.GetCustomAttributes(MemberInfo, bool), Attribute.IsDefined(MemberInfo, Type), Attribute.IsDefined(MemberInfo, Type, bool), Attribute.GetCustomAttribute(MemberInfo, Type), Attribute.GetCustomAttribute(MemberInfo, Type, bool), Attribute.GetCustomAttributes(ParameterInfo), Attribute.GetCustomAttributes(ParameterInfo, Type), Attribute.GetCustomAttributes(ParameterInfo, Type, bool), Attribute.GetCustomAttributes(ParameterInfo, bool), Attribute.IsDefined(ParameterInfo, Type), Attribute.IsDefined(ParameterInfo, Type, bool), Attribute.GetCustomAttribute(ParameterInfo, Type), Attribute.GetCustomAttribute(ParameterInfo, Type, bool), Attribute.GetCustomAttributes(Module, Type), Attribute.GetCustomAttributes(Module), Attribute.GetCustomAttributes(Module, bool), Attribute.GetCustomAttributes(Module, Type, bool), Attribute.IsDefined(Module, Type), Attribute.IsDefined(Module, Type, bool), Attribute.GetCustomAttribute(Module, Type), Attribute.GetCustomAttribute(Module, Type, bool), Attribute.GetCustomAttributes(Assembly, Type), Attribute.GetCustomAttributes(Assembly, Type, bool), Attribute.GetCustomAttributes(Assembly), Attribute.GetCustomAttributes(Assembly, bool), Attribute.IsDefined(Assembly, Type), Attribute.IsDefined(Assembly, Type, bool), Attribute.GetCustomAttribute(Assembly, Type), Attribute.GetCustomAttribute(Assembly, Type, bool), Attribute.Equals(object?), Attribute.GetHashCode(), Attribute.Match(object?), Attribute.IsDefaultAttribute(), Attribute.TypeId, object.GetType(), object.ToString(), object.Equals(object?), object.Equals(object?, object?), object.ReferenceEquals(object?, object?), object.GetHashCode()

Remarks

Marking is an explicit choice. Adding a new public method to a class does not automatically expose it to agents. This is the natural continuation of the code-only tools rule (tools are defined only in code).

The description field tells the model when to call the tool; if left empty, the model looks only at the name and parameter schema.

internal class OrderTools
{
    [TraconTool("get_order_status", "Returns an order's shipping status.")]
    public static string GetOrderStatus(string orderId) => "shipped";

    public static void Helper() { }   // not a tool
}

Constructors

TraconToolAttribute()

Creates a mark that uses the method name as the tool name.

public TraconToolAttribute()

TraconToolAttribute(string)

Creates a mark with an explicit tool name.

public TraconToolAttribute(string name)

Parameters

name string

The tool name. Used in agent definitions.

TraconToolAttribute(string, string)

Creates a mark with a name and a description.

public TraconToolAttribute(string name, string description)

Parameters

name string

The tool name. Used in agent definitions.

description string

The description telling the model when to call the tool.

Properties

Description

The description telling the model when to call the tool.

public string? Description { get; init; }

Property Value

string?

Effect

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

public ToolEffect Effect { get; init; }

Property Value

ToolEffect

JsonSerializerContext

The source-generated JSON context for a complex tool result, or null when the result needs no JSON serialization.

public Type? JsonSerializerContext { get; init; }

Property Value

Type?

Remarks

Set this to a JsonSerializerContext type that declares [JsonSerializable(typeof(TResult))]. The JSON source generator only sees source written by the tool owner; a context emitted by another source generator arrives too late for it to process.

MaxOutputBytes

The maximum UTF-8 byte count for this tool result. Zero uses the installation default.

public int MaxOutputBytes { get; init; }

Property Value

int

Remarks

This limit does not apply to AI.AIContent attachments. They use the existing attachment contract instead of an inline text result.

Name

The tool name. The method name is used if null.

public string? Name { get; }

Property Value

string?

RequiredPermission

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

public string? RequiredPermission { get; init; }

Property Value

string?

Remarks

Checked by the registered IToolAuthorizationHandler before every call.

RequiresApproval

Whether explicit approval is required before the call.

public bool RequiresApproval { get; init; }

Property Value

bool

Remarks

A marked tool is wrapped with ApprovalRequiredAIFunction in the registry. Microsoft Agent Framework produces an approval request instead of running the tool; the call waits until the user’s decision arrives. Mark tools that perform irreversible actions (cancellation, deletion, payment) this way.

SafeToRepeat

See TraconToolRegistration.SafeToRepeat. Defaults to false.

public bool SafeToRepeat { get; init; }

Property Value

bool

TimeoutSeconds

The longest duration this tool’s call may run, in seconds. Zero (the default) uses the installation default instead of a fixed value.

public int TimeoutSeconds { get; init; }

Property Value

int

Remarks

An attribute argument cannot be a TimeSpan, so seconds is the unit; the registry converts it.