# TraconToolRegistration

> Tracon documentation. Tracon is a .NET package family that adds a control
> plane on Microsoft Agent Framework, published as NuGet packages that run
> inside your own ASP.NET Core application.
>
> Page: https://tracon.dev/api/tracon.tracontoolregistration/
> Summary: TraconToolRegistration: A single tool registered with dependency injection. Tracon builds the tool registry from these registrations.

<div class="api-provenance">Namespace Tracon · Assembly <code>Tracon.Abstractions.dll</code></div>

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

```csharp
public sealed class TraconToolRegistration
```

<dl class="api-relations"><dt>Inheritance</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.object">object</a> ← <a href="/api/tracon.tracontoolregistration/">TraconToolRegistration</a></dd><dt>Inherited Members</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.object.gettype">object.GetType()</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.tostring">object.ToString()</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object)">object.Equals(object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object-system-object)">object.Equals(object?, object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.referenceequals">object.ReferenceEquals(object?, object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.gethashcode">object.GetHashCode()</a></dd></dl>

## 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.

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

## Constructors

### <a id="Tracon_TraconToolRegistration__ctor_Microsoft_Extensions_AI_AIFunctionDeclaration_"></a> TraconToolRegistration\(AIFunctionDeclaration\)

Creates a new tool registration with default settings.

```csharp
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](https://learn.microsoft.com/dotnet/api/system.argumentnullexception)

`function` is [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null).

 [TraconException](/api/tracon.traconexception/)

The tool name does not follow the tool naming rules.

## Properties

### <a id="Tracon_TraconToolRegistration_Effect"></a> Effect

The tool's effect class. Defaults to [ToolEffect.Read](/api/tracon.tooleffect/).

```csharp
public ToolEffect Effect { get; init; }
```

#### Property Value

 [ToolEffect](/api/tracon.tooleffect/)

### <a id="Tracon_TraconToolRegistration_Function"></a> Function

The registered tool.

```csharp
public AIFunctionDeclaration Function { get; }
```

#### Property Value

 AIFunctionDeclaration

### <a id="Tracon_TraconToolRegistration_MaxOutputBytes"></a> MaxOutputBytes

The most bytes (UTF-8) this tool's result may carry, or
[null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/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.

```csharp
public int? MaxOutputBytes { get; init; }
```

#### Property Value

 [int](https://learn.microsoft.com/dotnet/api/system.int32)?

#### 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.

### <a id="Tracon_TraconToolRegistration_RequiredPermission"></a> RequiredPermission

The permission name a caller must hold to call this tool, or
[null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) when the tool declares none.

```csharp
public string? RequiredPermission { get; init; }
```

#### Property Value

 [string](https://learn.microsoft.com/dotnet/api/system.string)?

### <a id="Tracon_TraconToolRegistration_RequiresApproval"></a> RequiresApproval

Whether explicit approval is required before the call. Defaults to
[false](https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool).

```csharp
public bool RequiresApproval { get; init; }
```

#### Property Value

 [bool](https://learn.microsoft.com/dotnet/api/system.boolean)

#### Remarks

[TraconToolRegistration.Function](/api/tracon.tracontoolregistration/#Tracon_TraconToolRegistration_Function) must be an `AI.AIFunction` when this is
[true](https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool): approval defers a server-side call, and a
client-side tool has no server-side body to approve.

### <a id="Tracon_TraconToolRegistration_SafeToRepeat"></a> SafeToRepeat

Whether this tool's call may run again when an interrupted run is
continued. Defaults to [false](https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool).

```csharp
public bool SafeToRepeat { get; init; }
```

#### Property Value

 [bool](https://learn.microsoft.com/dotnet/api/system.boolean)

#### Remarks

The default, [false](https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool), 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](https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool) (typically by carrying its own
idempotency key).

Only consulted for [ToolEffect.Destructive](/api/tracon.tooleffect/) and
[ToolEffect.External](/api/tracon.tooleffect/) tools, which are otherwise refused
for a continuation — setting this to [true](https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool) is how a
tool author opts a specific irreversible or externally visible call
back in. [ToolEffect.Read](/api/tracon.tooleffect/) and [ToolEffect.Write](/api/tracon.tooleffect/)
calls are always safe to continue and never consult this flag.

### <a id="Tracon_TraconToolRegistration_Source"></a> Source

The tool's source. [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) for tools defined in code;
the server name for tools coming from a remote MCP server.

```csharp
public string? Source { get; init; }
```

#### Property Value

 [string](https://learn.microsoft.com/dotnet/api/system.string)?

### <a id="Tracon_TraconToolRegistration_Timeout"></a> Timeout

The longest duration this tool's call may run, or [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null)
to use the installation default.

```csharp
public TimeSpan? Timeout { get; init; }
```

#### Property Value

 [TimeSpan](https://learn.microsoft.com/dotnet/api/system.timespan)?