Edit

Deploy a tool to Microsoft Discovery

After you publish your tool's container image to Azure Container Registry (ACR) and author its YAML definition, the next step is to register the tool with Microsoft Discovery as an Azure resource of type Microsoft.Discovery/tools. Once registered, agents in any project that has access to the tool can invoke it during investigations.

This article shows you how to:

  • Convert your YAML tool definition into the JSON format that the Discovery resource provider accepts.
  • Create the tool resource by using the Azure portal, the REST API, or Discovery Studio.
  • Optionally pass runtime environment variables to the tool's container at deployment time.

Prerequisites

Step 1: Convert the tool definition YAML to JSON

The Discovery resource provider stores the tool definition as a JSON document on the resource. You author the definition in YAML for readability, then convert it to JSON before uploading. Conversion changes the serialization format; it doesn't validate the deployed tool contract or test the container. First complete the local definition checks.

# Requires PowerShell 7+ with the powershell-yaml module
Install-Module powershell-yaml -Scope CurrentUser

$yaml = Get-Content -Raw ./tool.yaml | ConvertFrom-Yaml
$yaml | ConvertTo-Json -Depth 20 | Set-Content ./tool.json

Tip

Keep both the YAML source and the generated JSON in source control. The YAML is easier to review in pull requests; the JSON is what you upload to Discovery.

Step 2 (optional): Prepare an environment variables file

Environment variables let you pass runtime configuration to your tool's container without rebuilding the image. Use this when values vary per deployment (for example, endpoints, feature flags, model names, or non-secret tokens) and aren't pre-baked into the image.

The environment variables file is a JSON document containing a flat map of string keys to string values:

{
  "MODEL_ENDPOINT": "https://contoso-models.openai.azure.com/",
  "MAX_BATCH_SIZE": "32",
  "FEATURE_FLAG_NEW_PARSER": "true"
}

Save the file (for example, my-tool.env.json). You upload it alongside the definition file in step 3.

Important

Don't store secrets such as API keys or connection strings in the environment variables file. Use a managed identity with appropriate role assignments, or reference a Key Vault, instead.

Step 3: Create the tool resource

You can create the Discovery tool resource by using the Azure portal, the REST API, or Discovery Studio.

  1. Sign in to the Azure portal.

  2. Search for Microsoft Discovery Tools and select it.

  3. Select + Create. The Basics tab opens.

  4. On the Basics tab, fill in the following fields:

    Field Description
    Subscription The subscription where the tool resource is created.
    Resource group An existing resource group, or select Create new. Use the same resource group as your workspace for simpler management.
    Name A unique name for the tool resource. Use lowercase letters, numbers, and hyphens.
    Region An Azure region that supports Microsoft Discovery (East US, East US 2, Sweden Central, or UK South).
    Definition content file The JSON file produced in Step 1. Select the folder icon and upload tool.json.
    Definition content version Any string that identifies the version of the definition (for example, 1.0.0, 2026-05-01, or a git commits SHA). Increment this value each time you upload a new definition so that consumers can detect updates.
    Environment variables Optional. Upload the JSON file from Step 2. Leave blank if your container doesn't need runtime configuration.

    Screenshot of the Create Tool page in the Azure portal showing the Basics tab with Subscription, Resource group, Name, Region, Definition content file, Definition content version, and Environment variables fields.

  5. (Optional) On the Tags tab, add any tags required by your organization.

  6. On the Review + create tab, verify the settings and select Create.

After deployment completes, the tool appears in the Discovery tool catalog and can be added to projects.

Step 4: Verify the deployment

After you create the tool, verify that it deployed successfully. In Discovery Studio, open your project, select AI Capabilities > Tools, and then select All tools to confirm your tool appears in the list.

Screenshot of the Tools page in Discovery Studio showing the tools list.

You can also verify the deployment by using the Azure CLI:

az resource show \
  --ids "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Discovery/tools/<toolName>" \
  --api-version 2026-06-01 \
  --query "{name:name, state:properties.provisioningState, version:properties.version}" \
  -o table

The provisioningState should be Succeeded. Creating this resource doesn't automatically add it to every project or grant access to it. In each project that needs the tool, add the existing tool through AI Capabilities > Tools and ensure the invoking identities have the required permissions.

Update an existing tool

To publish a new version of a tool, repeat Step 1 with your updated YAML, then re-run Step 3 using the same tool name. Always increment Definition content version so that downstream consumers can detect the change.

Troubleshooting

Symptom Likely cause Resolution
InvalidDefinitionContent error during create The uploaded JSON doesn't match the tool definition schema. Re-validate the YAML with the tool definition reference and reconvert. See Create a tool definition.
ImagePullBackOff when the tool runs The image reference, registry permissions, or network access are incorrect. Verify the repository and tag, the supercomputer's kubelet UAMI image-pull permissions, and the network and DNS path. See Supercomputer registry access, including ABAC role differences.
Environment variables aren't visible in the container The file wasn't valid JSON or wasn't uploaded. Confirm the file is a flat { "KEY": "value" } JSON object and re-create the resource.
RoleAssignmentNotFound when creating the resource Missing RBAC on the resource group. Assign Contributor or Microsoft Discovery Platform Administrator (Preview) at the resource group scope.

Next steps