# ToolDescriptor

> 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.tooldescriptor/
> Summary: ToolDescriptor: The UI-facing definition of a tool registered in code. The agent editor shows a selection from this list; it does not accept free-text input.

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

The UI-facing definition of a tool registered in code. The agent editor
shows a selection from this list; it does not accept free-text input.

```csharp
public sealed record ToolDescriptor : IEquatable<ToolDescriptor>
```

<dl class="api-relations"><dt>Inheritance</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.object">object</a> ← <a href="/api/tracon.tooldescriptor/">ToolDescriptor</a></dd><dt>Implements</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.iequatable-1">IEquatable&lt;ToolDescriptor&gt;</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>

## Constructors

### <a id="Tracon_ToolDescriptor__ctor"></a> ToolDescriptor\(\)

```csharp
public ToolDescriptor()
```

## Properties

### <a id="Tracon_ToolDescriptor_Description"></a> Description

The description that lets the model understand when to call the tool.

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

#### Property Value

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

### <a id="Tracon_ToolDescriptor_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/)

#### Remarks

Information, not a gate — see [ToolEffect](/api/tracon.tooleffect/). An MCP-sourced
tool defaults to [ToolEffect.External](/api/tracon.tooleffect/) instead: its
definition lives on a remote server and can change, so the most
cautious class is the honest default.

### <a id="Tracon_ToolDescriptor_HostedKind"></a> HostedKind

The kind of a hosted tool, or [null](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/null) for a tool Tracon calls.

```csharp
public HostedToolKind? HostedKind { get; init; }
```

#### Property Value

 [HostedToolKind](/api/tracon.hostedtoolkind/)?

#### Remarks

A hosted tool (`AddHostedTool`) runs on the model provider's side inside the model
call. Tracon puts no timeout, approval or permission in front of it, so
[ToolDescriptor.RequiresApproval](/api/tracon.tooldescriptor/#Tracon_ToolDescriptor_RequiresApproval), [ToolDescriptor.RequiredPermission](/api/tracon.tooldescriptor/#Tracon_ToolDescriptor_RequiredPermission) and [ToolDescriptor.Timeout](/api/tracon.tooldescriptor/#Tracon_ToolDescriptor_Timeout)
stay empty. The UI shows this field as a *separate badge*, and the provider's
API surface decides whether the kind runs (the agent validation names a surface that
does not).

### <a id="Tracon_ToolDescriptor_JsonSchema"></a> JsonSchema

The arguments' JSON schema.

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

#### Property Value

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

### <a id="Tracon_ToolDescriptor_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
(`TraconOptions.Tools.DefaultMaxOutputBytes`).

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

#### Property Value

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

### <a id="Tracon_ToolDescriptor_Name"></a> Name

The tool name. Used in agent definitions.

```csharp
public required string Name { get; init; }
```

#### Property Value

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

### <a id="Tracon_ToolDescriptor_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)?

#### Remarks

Passed to [IToolAuthorizationHandler](/api/tracon.itoolauthorizationhandler/) as-is; Tracon
does not resolve or validate its meaning.

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

Whether explicit approval is required before the call.

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

#### Property Value

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

#### Remarks

If [true](https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool), the compiler wraps the tool with
`ApprovalRequiredAIFunction`; Microsoft Agent Framework produces a
`ToolApprovalRequestContent` instead of running the tool, and the
call waits for the user's approval. A code tool also reports
[true](https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool) when its function is already wrapped in
`ApprovalRequiredAIFunction`, whatever its registration says: the
framework asks for approval either way.

### <a id="Tracon_ToolDescriptor_RunsOnClient"></a> RunsOnClient

Whether the tool's body runs on the caller (typically a browser)
instead of on the server.

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

#### Property Value

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

#### Remarks

A client-side tool (`AddClientTool`) is registered as a
declaration only: the model can call it, but the server never runs
it. The caller must send the result back via
`AgentRunRequest.ToolResults` for the run to continue.

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

Whether this tool's call may run again when an interrupted run is
continued. See `TraconToolRegistration.SafeToRepeat`.

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

#### Property Value

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

### <a id="Tracon_ToolDescriptor_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)?

#### Remarks

The UI shows this field as a *separate badge*: the tool
definition lives not in code but on a remote server, and that server
may change the definition.

### <a id="Tracon_ToolDescriptor_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 (`TraconOptions.Tools.DefaultTimeout`).

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

#### Property Value

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

## Methods

### <a id="Tracon_ToolDescriptor_Equals_System_Object_"></a> Equals\(object?\)

```csharp
public override bool Equals(object? obj)
```

#### Parameters

`obj` [object](https://learn.microsoft.com/dotnet/api/system.object)?

#### Returns

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

### <a id="Tracon_ToolDescriptor_Equals_Tracon_ToolDescriptor_"></a> Equals\(ToolDescriptor?\)

```csharp
public bool Equals(ToolDescriptor? other)
```

#### Parameters

`other` [ToolDescriptor](/api/tracon.tooldescriptor/)?

#### Returns

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

### <a id="Tracon_ToolDescriptor_GetHashCode"></a> GetHashCode\(\)

```csharp
public override int GetHashCode()
```

#### Returns

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

### <a id="Tracon_ToolDescriptor_ToString"></a> ToString\(\)

```csharp
public override string ToString()
```

#### Returns

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

## Operators

### <a id="Tracon_ToolDescriptor_op_Equality_Tracon_ToolDescriptor_Tracon_ToolDescriptor_"></a> operator ==\(ToolDescriptor?, ToolDescriptor?\)

```csharp
public static bool operator ==(ToolDescriptor? left, ToolDescriptor? right)
```

#### Parameters

`left` [ToolDescriptor](/api/tracon.tooldescriptor/)?

`right` [ToolDescriptor](/api/tracon.tooldescriptor/)?

#### Returns

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

### <a id="Tracon_ToolDescriptor_op_Inequality_Tracon_ToolDescriptor_Tracon_ToolDescriptor_"></a> operator \!=\(ToolDescriptor?, ToolDescriptor?\)

```csharp
public static bool operator !=(ToolDescriptor? left, ToolDescriptor? right)
```

#### Parameters

`left` [ToolDescriptor](/api/tracon.tooldescriptor/)?

`right` [ToolDescriptor](/api/tracon.tooldescriptor/)?

#### Returns

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