Azure AI Foundry Toolbox Skills Not Being Discovered or Read by Agents

Girija Sravya Peesapati (US) 0 Reputation points
2026-10-05T09:30:11.2133333+00:00

An issue is being observed with Skills configured inside Toolboxes in Azure AI Foundry.

A Skill is added to a Toolbox using a Markdown skill definition and the Toolbox is associated with an Azure AI Foundry agent. However, the agent is unable to discover, read, or use the Skill available within the Toolbox.

Observed Issue

  • The Skill is added to the Toolbox successfully.
  • The agent does not recognize the Skill as an available resource or capability.
  • Prompts explicitly requesting the agent to locate, read, or use the Skill do not result in successful Skill discovery.
  • The Markdown Skill definition does not appear to be retrieved or interpreted by the agent.
  • The Skill therefore cannot be invoked or used during agent execution.
    User's imageUser's image

The issue appears to be specifically related to Skill discovery and access from a Toolbox within the Azure AI Foundry agent runtime.

Clarification is required on the following:

Is any additional configuration required for an agent to identify and read Skills from a Toolbox?

Are there specific requirements for the Skill Markdown structure, location, permissions, or Toolbox configuration?

Does the current Azure AI Foundry agent runtime support Skill discovery through the Toolbox/MCP resource mechanism?

Is the inability to discover or read Toolbox Skills a known limitation of the current preview implementation?

The primary issue is that Skills configured within a Toolbox are not being discovered or read by the Azure AI Foundry agent, preventing them from being used during agent execution.An issue is being observed with Skills configured inside Toolboxes in Azure AI Foundry.

Foundry Tools
Foundry Tools

Formerly known as Azure AI Services or Azure Cognitive Services is a unified collection of prebuilt AI capabilities within the Microsoft Foundry platform

0 comments

3 answers

Sort by: Most helpful
Most helpful Newest Oldest
  1. Hemant Bharadwaj 340 Reputation points Microsoft Employee
    2026-10-27T15:01:08.13+00:00

    Likely cause: your toolbox connection is working for tools, but skill discovery from toolbox resources appears to be a preview/runtime-path limitation for this agent flow rather than a general connectivity problem.

    How to isolate it cleanly:

    1. Confirm agent type and execution path (prompt agent vs hosted agent) and record SDK/API versions used at runtime.
    2. Keep one minimal markdown skill (single skill, minimal metadata) and one simple tool in the same toolbox.
    3. Run a controlled test prompt and compare traces:
      • Tool appears and is invoked
      • Skill resource never appears or is never selected
    4. If this pattern is consistent, treat it as current runtime support limitation for that path and open a support ticket with run IDs/toolbox ID/agent ID.

    What docs currently show:

    • Prompt-agent support is clearly documented for responses/A2A endpoint scenarios.
    • Hosted-agent documentation describes toolbox/tool usage, but does not clearly guarantee universal skill discovery behavior across every preview/runtime path.

    Practical workaround now:

    1. Expose required behavior as explicit tools callable by the agent.
    2. Keep skills as optional metadata until your tenant/runtime path confirms support.
    3. Re-test after SDK/API updates because preview behavior can change.

    Validation checklist:

    1. New toolbox + new agent (clean objects) to rule out stale config.
    2. Confirm RBAC scope for project/agent/toolbox is consistent.
    3. Confirm same result across two separate runs with different prompts.

    References:

    “If you find this answer helpful, please upvote it. If this resolves your issue, please mark it as the accepted answer so that it can help others in the community.”

    Was this answer helpful?

    0 comments
  2. Anna Gentek 0 Reputation points
    2026-10-27T14:22:56.3166667+00:00

    Does this apply to prompt agents or only hosted agents?

    Was this answer helpful?

    0 comments

  3. AI answer

    2026-10-05T09:30:38.4833333+00:00

    Yes. Skill discovery through a Toolbox is supported in the current preview, but several conditions must be met for the agent runtime to discover and load the skill.

    Key requirements:

    1. Skill and toolbox must be in the same Foundry project Cross-project skill references are not supported. If the skill was created in a different Foundry project, the toolbox can’t expose it correctly to the agent runtime.
    2. The toolbox version must actually include the skill reference A toolbox version can contain tools, skills, or both. When attaching a skill, the reference uses the skill name and optionally a version.
      • If version is omitted, the toolbox uses the skill’s default_version.
      • If version is specified, it pins that immutable version.
    3. The client/runtime must support MCP Resources Skills attached to a toolbox are exposed through the toolbox MCP endpoint as MCP Resources, not ordinary callable tools. The agent framework or MCP client must support the MCP Resources protocol to auto-discover and load them.
    4. Verify discovery at the toolbox MCP endpoint The documented validation step is to call resources/list on the toolbox MCP endpoint and confirm the skill name appears. If the skill does not appear there, the problem is in toolbox/skill attachment or publishing, not in prompting.
    5. Publish the toolbox version after imperative changes If the skill was added with imperative azd commands, the toolbox version must be published before clients can discover the attached skill.
    6. Skill package and markdown must be valid If the skill definition itself is malformed, creation may succeed inconsistently or the skill may not behave correctly. The documented checks are:
      • SKILL.md must contain unquoted name and description values.
      • name must use lowercase letters, numbers, and hyphens.
      • The file name must match the skill name supplied to the CLI.
      • If uploaded as an archive, use a ZIP containing SKILL.md, or supported individual files.
    7. For downloaded/hosted agent loading scenarios, folder layout matters If the issue is with a hosted agent loading a downloaded skill package, each skill must be extracted into its own subdirectory such as skills/greeting/SKILL.md, then the agent must be restarted so it reads the skill at startup.

    What the current behavior means:

    • If the agent does not “see” the skill, that is usually a discovery problem, not an instruction problem.
    • Prompting the agent to “read the skill” will not fix discovery if the skill is not being exposed as an MCP Resource.
    • This is not documented as an unsupported scenario. The preview documentation explicitly states that skills can be attached to a toolbox and made available to agents through the toolbox MCP endpoint.

    Recommended troubleshooting path:

    1. Confirm the skill and toolbox are in the same Foundry project.
    2. Confirm the toolbox version includes the skill reference by name, and the intended version/default version is valid.
    3. If the skill was added after toolbox creation, publish the toolbox version.
    4. Validate the skill appears from the toolbox MCP endpoint via resources/list.
    5. Validate the skill definition format in SKILL.md:
      • unquoted name and description
      • lowercase/hyphenated name
      • matching file name
    6. If the skill was uploaded as a ZIP, confirm the archive shape is supported.
    7. If using a hosted agent with downloaded skills, confirm the extracted folder structure and restart the agent.
    8. If discovery still fails, review project networking, especially if private networking is enabled.

    Based on the documented behavior, the most likely causes are:

    • skill and toolbox are in different projects
    • toolbox version was not published after adding the skill
    • runtime/client does not support MCP Resources
    • the skill package or SKILL.md structure is invalid
    AI-generated content may be incorrect. Read our transparency notes for more information.

    Was this answer helpful?

Your answer

Answers can be marked as 'Accepted' by the question author and 'Recommended' by moderators, which helps users know the answer solved the author's problem.