# 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/http-api/schemas/tooldescriptor/
> Summary: OpenAPI request or response schema for ToolDescriptor, including required fields, defaults, constraints, and linked nested types.

[← All HTTP schemas](/http-api/schemas/)

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.

**Shape:** `object`

| Property | Required | Type | Description | Rules |
|---|---|---|---|---|
| `name` | yes | `string` | The tool name. Used in agent definitions. | — |
| `description` | no | `string` | The description that lets the model understand when to call the tool. | — |
| `jsonSchema` | no | `string` | The arguments' JSON schema. | — |
| `requiresApproval` | no | `boolean` | Whether explicit approval is required before the call. | — |
| `source` | no | `string` | The tool's source. `null` for tools defined in code; the server name for tools coming from a remote MCP server. | — |
| `runsOnClient` | no | `boolean` | Whether the tool's body runs on the caller (typically a browser) instead of on the server. | — |
| `hostedKind` | no | `null` oneOf [`HostedToolKind`](/http-api/schemas/hostedtoolkind/) | — | — |
| `effect` | no | [`ToolEffect`](/http-api/schemas/tooleffect/) | The tool's effect class. Defaults to ToolEffect.Read. | — |
| `requiredPermission` | no | `string` | The permission name a caller must hold to call this tool, or `null` when the tool declares none. | — |
| `timeout` | no | `string` | The longest duration this tool's call may run, or `null` to use the installation default (`TraconOptions.Tools.DefaultTimeout`). | pattern `^-?(\d+\.)?\d{2}:\d{2}:\d{2}(\.\d{1,7})?$` |
| `safeToRepeat` | no | `boolean` | Whether this tool's call may run again when an interrupted run is continued. See `TraconToolRegistration.SafeToRepeat`. | — |
| `maxOutputBytes` | no | `integer (int32)` | The most bytes (UTF-8) this tool's result may carry, or `null` to use the installation default (`TraconOptions.Tools.DefaultMaxOutputBytes`). | pattern `^-?(?:0\\|[1-9]\d*)$` |