AgentPrismToolAttribute

Namespace AgentPrism · Assembly AgentPrism.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 AgentPrismToolAttribute : Attribute

Inheritance

object ← Attribute ← AgentPrismToolAttribute

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 static class OrderTools
{
    [AgentPrismTool("get_order_status", "Returns an order's shipping status.")]
    public static string GetOrderStatus(string orderId) => ...;

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

Constructors

AgentPrismToolAttribute()

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

public AgentPrismToolAttribute()

AgentPrismToolAttribute(string)

Creates a mark with an explicit tool name.

public AgentPrismToolAttribute(string name)

Parameters

name string

The tool name. Used in agent definitions.

AgentPrismToolAttribute(string, string)

Creates a mark with a name and a description.

public AgentPrismToolAttribute(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

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.

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.