# FoundryToolboxBuilderExtensions Methods

- Package: [Aspire.Hosting.Foundry](/reference/api/csharp/aspire.hosting.foundry.md)
- Type: [FoundryToolboxBuilderExtensions](/reference/api/csharp/aspire.hosting.foundry/foundrytoolboxbuilderextensions.md)
- Kind: `Methods`
- Members: `9`

Extension methods for adding Microsoft Foundry Toolbox resources and tools.

<a id="addtoolbox"></a>
<a id="addtoolbox-iresourcebuilder-azurecognitiveservicesprojectresource-string-action-foundrytoolboxresource"></a>

## AddToolbox(IResourceBuilder<AzureCognitiveServicesProjectResource>, string, Action<FoundryToolboxResource>)

- Name: `AddToolbox(IResourceBuilder<AzureCognitiveServicesProjectResource>, string, Action<FoundryToolboxResource>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<FoundryToolboxResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Foundry/Toolbox/FoundryToolboxBuilderExtensions.cs#L50-L67)

Adds a Microsoft Foundry Toolbox endpoint to a Microsoft Foundry project.

```csharp
public static class FoundryToolboxBuilderExtensions
{
    public static IResourceBuilder<FoundryToolboxResource> AddToolbox(
        this IResourceBuilder<AzureCognitiveServicesProjectResource> builder,
        string name,
        Action<FoundryToolboxResource>? configure = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<AzureCognitiveServicesProjectResource>`)
  The resource builder for the Microsoft Foundry project.
- `name` (`string`)
  The Toolbox name.
- `configure` (`Action<FoundryToolboxResource>`) `optional`
  Optional callback used to configure the Toolbox resource.

## Returns

`IResourceBuilder<FoundryToolboxResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1` for the Toolbox resource.

## Remarks

Aspire reuses the current default version when its configuration matches. Otherwise, it creates and promotes a new immutable version. The [FoundryToolboxResource.Version](/reference/api/csharp/aspire.hosting.foundry/foundrytoolboxresource/properties.md#version) property pins the version used by consumers in the MCP endpoint URI; the version selected by the most recent reconciliation is exposed via [FoundryToolboxResource.DeployedVersion](/reference/api/csharp/aspire.hosting.foundry/foundrytoolboxresource/properties.md#deployedversion).

## Examples

```csharp
var foundry = builder.AddFoundry("foundry");
var project = foundry.AddProject("project");
var toolbox = project.AddToolbox("field-tools")
    .WithWebSearchTool();

builder.AddProject<Projects.Worker>("worker")
    .WithReference(toolbox)
    .WaitFor(toolbox);
```

## ATS metadata

### Ignored by ATS

- Reason: Polyglot AppHosts use the FoundryToolboxOptions overload instead.

<a id="asexisting"></a>
<a id="asexisting-iresourcebuilder-foundrytoolboxresource"></a>

## AsExisting(IResourceBuilder<FoundryToolboxResource>)

- Name: `AsExisting(IResourceBuilder<FoundryToolboxResource>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<FoundryToolboxResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Foundry/Toolbox/FoundryToolboxBuilderExtensions.cs#L155-L159)

Uses an existing Microsoft Foundry Toolbox during local runs and deployment.

```csharp
public static class FoundryToolboxBuilderExtensions
{
    public static IResourceBuilder<FoundryToolboxResource> AsExisting(
        this IResourceBuilder<FoundryToolboxResource> builder)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<FoundryToolboxResource>`)
  The resource builder for the Toolbox.

## Returns

`IResourceBuilder<FoundryToolboxResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1` for chaining.

## Remarks

Existing mode validates that the remote Toolbox and optional pinned [FoundryToolboxResource.Version](/reference/api/csharp/aspire.hosting.foundry/foundrytoolboxresource/properties.md#version) exist without resolving locally modeled tools or mutating the Toolbox.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="publishasexisting"></a>
<a id="publishasexisting-iresourcebuilder-foundrytoolboxresource"></a>

## PublishAsExisting(IResourceBuilder<FoundryToolboxResource>)

- Name: `PublishAsExisting(IResourceBuilder<FoundryToolboxResource>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<FoundryToolboxResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Foundry/Toolbox/FoundryToolboxBuilderExtensions.cs#L130-L137)

Reconciles a Microsoft Foundry Toolbox during local runs and uses an existing Toolbox during deployment.

```csharp
public static class FoundryToolboxBuilderExtensions
{
    public static IResourceBuilder<FoundryToolboxResource> PublishAsExisting(
        this IResourceBuilder<FoundryToolboxResource> builder)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<FoundryToolboxResource>`)
  The resource builder for the Toolbox.

## Returns

`IResourceBuilder<FoundryToolboxResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1` for chaining.

## Remarks

Existing mode validates that the remote Toolbox and optional pinned [FoundryToolboxResource.Version](/reference/api/csharp/aspire.hosting.foundry/foundrytoolboxresource/properties.md#version) exist without resolving locally modeled tools or mutating the Toolbox.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="runasexisting"></a>
<a id="runasexisting-iresourcebuilder-foundrytoolboxresource"></a>

## RunAsExisting(IResourceBuilder<FoundryToolboxResource>)

- Name: `RunAsExisting(IResourceBuilder<FoundryToolboxResource>)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<FoundryToolboxResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Foundry/Toolbox/FoundryToolboxBuilderExtensions.cs#L105-L112)

Uses an existing Microsoft Foundry Toolbox during local runs and reconciles it during deployment.

```csharp
public static class FoundryToolboxBuilderExtensions
{
    public static IResourceBuilder<FoundryToolboxResource> RunAsExisting(
        this IResourceBuilder<FoundryToolboxResource> builder)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<FoundryToolboxResource>`)
  The resource builder for the Toolbox.

## Returns

`IResourceBuilder<FoundryToolboxResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1` for chaining.

## Remarks

Existing mode validates that the remote Toolbox and optional pinned [FoundryToolboxResource.Version](/reference/api/csharp/aspire.hosting.foundry/foundrytoolboxresource/properties.md#version) exist without resolving locally modeled tools or mutating the Toolbox.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withaisearchtool"></a>
<a id="withaisearchtool-iresourcebuilder-foundrytoolboxresource-string-iresourcebuilder-azuresearchresource-string-string"></a>

## WithAISearchTool(IResourceBuilder<FoundryToolboxResource>, string, IResourceBuilder<AzureSearchResource>, string, string?)

- Name: `WithAISearchTool(IResourceBuilder<FoundryToolboxResource>, string, IResourceBuilder<AzureSearchResource>, string, string?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<FoundryToolboxResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Foundry/Toolbox/FoundryToolboxBuilderExtensions.cs#L314-L342)

Adds an Azure AI Search tool definition to the Toolbox.

```csharp
public static class FoundryToolboxBuilderExtensions
{
    public static IResourceBuilder<FoundryToolboxResource> WithAISearchTool(
        this IResourceBuilder<FoundryToolboxResource> builder,
        string name,
        IResourceBuilder<AzureSearchResource> search,
        string indexName,
        string? description = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<FoundryToolboxResource>`)
  The resource builder for the Toolbox.
- `name` (`string`)
  The tool name.
- `search` (`IResourceBuilder<AzureSearchResource>`)
  The Azure AI Search resource backing the tool.
- `indexName` (`string`)
  The search index name.
- `description` (`string?`) `optional`
  An optional description of the Azure AI Search tool.

## Returns

`IResourceBuilder<FoundryToolboxResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1` for chaining.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withdescription"></a>
<a id="withdescription-iresourcebuilder-foundrytoolboxresource-string"></a>

## WithDescription(IResourceBuilder<FoundryToolboxResource>, string)

- Name: `WithDescription(IResourceBuilder<FoundryToolboxResource>, string)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<FoundryToolboxResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Foundry/Toolbox/FoundryToolboxBuilderExtensions.cs#L200-L205)

Sets the description persisted with each Toolbox version.

```csharp
public static class FoundryToolboxBuilderExtensions
{
    public static IResourceBuilder<FoundryToolboxResource> WithDescription(
        this IResourceBuilder<FoundryToolboxResource> builder,
        string description)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<FoundryToolboxResource>`)
  The resource builder for the Toolbox.
- `description` (`string`)
  The Toolbox description.

## Returns

`IResourceBuilder<FoundryToolboxResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1` for chaining.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.

<a id="withmcptool"></a>
<a id="withmcptool-iresourcebuilder-foundrytoolboxresource-string-string-foundrytoolboxmcptooloptions"></a>

## WithMcpTool(IResourceBuilder<FoundryToolboxResource>, string, string, FoundryToolboxMcpToolOptions?)

- Name: `WithMcpTool(IResourceBuilder<FoundryToolboxResource>, string, string, FoundryToolboxMcpToolOptions?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<FoundryToolboxResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Foundry/Toolbox/FoundryToolboxBuilderExtensions.cs)

Adds an MCP tool definition to the Toolbox.

```csharp
public static class FoundryToolboxBuilderExtensions
{
    public static IResourceBuilder<FoundryToolboxResource> WithMcpTool(
        this IResourceBuilder<FoundryToolboxResource> builder,
        string name,
        string endpoint,
        FoundryToolboxMcpToolOptions? options = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<FoundryToolboxResource>`)
  The resource builder for the Toolbox.
- `name` (`string`)
  The tool name.
- `endpoint` (`string`)
  The MCP endpoint URI.
- `options` ([FoundryToolboxMcpToolOptions?](/reference/api/csharp/aspire.hosting.foundry/foundrytoolboxmcptooloptions.md)) `optional`
  Optional MCP server metadata and approval policy.

## Returns

`IResourceBuilder<FoundryToolboxResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1` for chaining.

## ATS metadata

### Ignored by ATS

- Reason: Polyglot AppHosts use the union overload instead.

<a id="withmcptool-iresourcebuilder-foundrytoolboxresource-string-endpointreference-foundrytoolboxmcptooloptions"></a>

## WithMcpTool(IResourceBuilder<FoundryToolboxResource>, string, EndpointReference, FoundryToolboxMcpToolOptions?)

- Name: `WithMcpTool(IResourceBuilder<FoundryToolboxResource>, string, EndpointReference, FoundryToolboxMcpToolOptions?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<FoundryToolboxResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Foundry/Toolbox/FoundryToolboxBuilderExtensions.cs)

Adds an MCP tool definition to the Toolbox.

```csharp
public static class FoundryToolboxBuilderExtensions
{
    public static IResourceBuilder<FoundryToolboxResource> WithMcpTool(
        this IResourceBuilder<FoundryToolboxResource> builder,
        string name,
        EndpointReference endpoint,
        FoundryToolboxMcpToolOptions? options = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<FoundryToolboxResource>`)
  The resource builder for the Toolbox.
- `name` (`string`)
  The tool name.
- `endpoint` (`EndpointReference`)
  The MCP endpoint.
- `options` ([FoundryToolboxMcpToolOptions?](/reference/api/csharp/aspire.hosting.foundry/foundrytoolboxmcptooloptions.md)) `optional`
  Optional MCP server metadata and approval policy.

## Returns

`IResourceBuilder<FoundryToolboxResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1` for chaining.

## Remarks

During local development, the endpoint must resolve to a Foundry-reachable HTTPS URI, such as an anonymous development tunnel. A localhost endpoint cannot be reached by the Foundry data plane. Resource endpoints deployed with public HTTPS ingress can be referenced directly when using `aspire deploy`.

## ATS metadata

### Ignored by ATS

- Reason: Polyglot AppHosts use the union overload instead.

<a id="withwebsearchtool"></a>
<a id="withwebsearchtool-iresourcebuilder-foundrytoolboxresource-string-string"></a>

## WithWebSearchTool(IResourceBuilder<FoundryToolboxResource>, string, string?)

- Name: `WithWebSearchTool(IResourceBuilder<FoundryToolboxResource>, string, string?)`
- Modifiers: `extension`
- Returns: `IResourceBuilder<FoundryToolboxResource>`
- Source: [GitHub](https://github.com/microsoft/aspire/blob/f4c27f2d43ddc1cacd0dd083b30d1fea1cee7a62/src/Aspire.Hosting.Foundry/Toolbox/FoundryToolboxBuilderExtensions.cs#L176-L185)

Adds a web search tool definition to the Toolbox.

```csharp
public static class FoundryToolboxBuilderExtensions
{
    public static IResourceBuilder<FoundryToolboxResource> WithWebSearchTool(
        this IResourceBuilder<FoundryToolboxResource> builder,
        string name = "web-search",
        string? description = null)
    {
        // ...
    }
}
```

## Parameters

- `builder` (`IResourceBuilder<FoundryToolboxResource>`)
  The resource builder for the Toolbox.
- `name` (`string`) `optional`
  The tool name.
- `description` (`string?`) `optional`
  An optional description of the web search tool.

## Returns

`IResourceBuilder<FoundryToolboxResource>` -- A reference to the `ApplicationModel.IResourceBuilder`1` for chaining.

## ATS metadata

### ATS export

- Available to Polyglot AppHosts through the Aspire Type System.