Microsoft Foundry tool connections are where an agent’s reasoning meets external authority. A model can decide that it needs customer data, a search result, a calculation, or an operational action, but the connection determines how that tool is reached and which identity is allowed to use it. Foundry Agent Service supports built-in capabilities and custom integrations through functions, OpenAPI specifications, Model Context Protocol servers, and reusable toolboxes. The engineering challenge is not merely connecting more tools; it is exposing a small, governed capability surface that the agent can select correctly and operate safely.
In a broader Microsoft AI agent architecture, tool connections should be designed as security and interface boundaries. The same distinction is important for Microsoft AI-103: tools make an agent useful because they connect it to data and actions, but every connection adds identity, authorization, schema, failure, and observability concerns that the model itself cannot solve.
Separate the tool contract from the credential contract
A tool tells the agent what operation is available: search an index, retrieve an order, create a ticket, calculate a value, or call another service. A connection tells the runtime how to reach and authenticate to the system behind that operation. Keeping those concepts separate improves reuse and security. The same OpenAPI operation, for example, can be understood from its schema while the credential is stored and managed as a project connection rather than embedded in agent instructions or application code.
Foundry’s current toolbox model reinforces that separation. Toolboxes can group multiple tools behind a managed MCP-compatible endpoint while project connections hold authentication configuration. Microsoft documentation explicitly recommends creating the credential records separately and referencing them from toolbox configuration rather than placing secrets in the toolbox definition. That allows tooling to be versioned without copying credentials into every agent.
This distinction also clarifies troubleshooting. If the model selects the wrong operation, investigate tool naming, descriptions, and schemas. If the correct operation returns 401 or 403, investigate the connection identity and downstream authorization. Combining those failures into one generic “tool problem” makes both harder to diagnose.
Choose authentication based on whose authority should be exercised
Foundry supports several authentication patterns depending on the tool and integration, including key-based access, project managed identity, agent identity, OAuth identity passthrough, user Entra tokens, and unauthenticated access where appropriate. The technical choice should follow an authorization question: should this call use a shared service identity, the agent’s own workload identity, or the signed-in user’s delegated authority?
A shared identity is useful when the agent performs a service function with a clearly bounded permission set. A published agent identity can support agent-specific authorization so one agent does not automatically inherit another agent’s access. User identity passthrough is appropriate when downstream permissions must remain tied to the person who initiated the request. Each model has different operational implications for consent, RBAC, token handling, and audit evidence.
The principles in agent access and approval apply directly. Never choose authentication only because it is easiest to configure. Choose it because it preserves the intended authority boundary, then grant the narrowest permissions the tool requires.
Use OpenAPI when the contract is already an API
OpenAPI tools are a natural fit when the target service already exposes a stable HTTP interface described by OpenAPI 3.0 or 3.1. The specification gives the agent a structured set of operations, parameters, and response shapes. Strong operation IDs and descriptions matter because the model uses that metadata to decide which operation to call and how to populate inputs.
An OpenAPI connection should expose purpose-built operations rather than the entire administrative surface of a large API. If the agent needs to retrieve order status and create a support note, those can be narrow operations even when the backend API contains dozens of unrelated endpoints. Reducing the visible surface improves tool selection and limits the consequences of prompt manipulation or orchestration mistakes.
Schema design matters too. Prefer clear parameter names, constrained enumerations, explicit required fields, and structured responses. If an operation accepts a free-form object with many optional fields, the agent has more opportunities to produce semantically invalid requests. The tool-use mental model is useful here: the model needs a contract it can reason about, not a raw backend interface designed for human developers.
Use MCP for reusable, discoverable tool services
Model Context Protocol gives Foundry agents a standardized way to discover and call tools exposed by remote MCP servers. Foundry can connect custom MCP servers and can also expose a toolbox itself through an MCP-compatible endpoint. This creates a useful layering option: teams can build reusable tool services, govern them centrally, and allow multiple agents or runtimes to consume the same capability set.
MCP does not remove normal security responsibilities. The remote server still needs authentication, authorization, input validation, output filtering, and operational monitoring. Foundry connections can use keys, Microsoft Entra identities, or OAuth passthrough depending on the scenario. The agent should see only the subset of MCP tools it needs, especially when a server exposes administrative or high-impact operations.
Tool descriptions remain critical because MCP discovery can present several capabilities to the model. A large server with poorly differentiated tool names increases selection ambiguity. Curate allowed tools, write specific descriptions, and use approval controls for operations whose impact warrants an explicit boundary.
Toolboxes centralize reuse, governance, and versioning
A Foundry toolbox groups tools into a reusable unit and exposes them behind one managed endpoint. Microsoft positions toolboxes as a way to centralize authentication, governance, and versioning so teams can update a capability set once rather than rewiring every agent. That becomes valuable as the number of agents grows and the same enterprise services are used repeatedly.
Versioning is more than deployment convenience. A tool description change, schema change, authentication change, or allowed-tool change can alter agent behavior. A new toolbox version can be tested before it becomes the default, and version-specific endpoints can support controlled validation. The agent architecture can then promote a tested tool surface instead of receiving unreviewed changes automatically.
The existing agent lifecycle should include toolbox versions in release evidence. Record which agent version used which toolbox version, which downstream permissions were assigned, and what tests were run. Without that mapping, a production regression may be impossible to reproduce after the toolbox changes.
Descriptions and schemas determine whether the agent picks the right tool
Foundry documentation recommends adding a description to each toolbox tool so the model can select the correct capability. This is not cosmetic. Tool names, descriptions, and input schemas are part of the planner’s decision surface. If two tools overlap semantically, the model can make a reasonable but wrong choice even when both APIs work exactly as designed.
Descriptions should state the business purpose, eligibility conditions, authoritative data source, and key exclusions. “Gets customer information” is weak. “Returns the current shipping status for an order ID; do not use for billing or account-profile data” is far more useful. Parameters should use domain language and distinguish identifiers that may otherwise be confused.
The actions and connectors principle applies here as well: every capability needs a clear boundary in the agent’s world. When the tool surface grows, periodically remove obsolete or redundant operations so the model is not choosing among historical leftovers.
Design approval and least privilege around side effects
Read-only retrieval and side-effecting operations should not be treated as equivalent. A search tool can still expose sensitive data, but an action that deletes, approves, publishes, purchases, or changes permissions carries a different failure cost. Give high-impact tools narrower authorization, stronger validation, and approval requirements appropriate to the risk.
Foundry’s MCP and toolbox patterns can support tool approval behavior, but approval is only one control. The backend service must still enforce authorization. Never depend on a prompt instruction such as “only managers can approve” if the tool credential itself can approve for anyone. The downstream service should receive an identity and context it can validate independently.
This is the core lesson of autonomous agent security: the model can propose an action, but the system around the model determines whether that action is authorized and executable. Tool connections are one of the most important places to enforce that separation.
Trace tool calls as first-class operational events
Foundry Agent Service supports tracing across model calls and tool invocations. Production operations should use that evidence to correlate user or event input, selected tool, connection identity, request parameters, response status, latency, and resulting side effect. Sensitive payloads may need redaction, but the system should still retain enough metadata to explain what happened.
Tool-level metrics reveal problems that an end-to-end success rate can hide. Track selection frequency, authorization failures, timeouts, schema errors, retries, approval denials, and downstream service latency. If an agent suddenly begins calling a costly or privileged tool more often, investigate the change even if user-facing responses remain plausible.
A clean troubleshooting path often starts by separating model selection, connection, and backend failures. The Foundry project design should make those layers observable. The model decides what to call, Foundry connects and authenticates, and the external service executes the operation. Evidence at each boundary turns “the agent failed” into a specific, actionable diagnosis.
Build a small governed tool surface and expand only when necessary
The strongest tool architecture is usually smaller than the raw set of APIs available to the organization. Start from the tasks the agent must perform and expose only the capabilities required for those tasks. Give each tool a clear description and schema, choose authentication that matches the intended authority, test ambiguous selection cases, and keep side-effecting operations behind deterministic validation or approval.
As reuse grows, consolidate shared tools into versioned toolboxes or reusable MCP services. Keep credentials in managed project connections, preserve least privilege, and test new toolbox versions with representative agent workloads before promotion. This creates a platform that can grow without copying the same authentication and governance logic into every agent.
Tool connections are therefore the operational boundary between language-model reasoning and enterprise systems. Foundry gives teams several integration mechanisms, but the architecture still has to answer the hard questions: what may the agent do, on whose authority, through which contract, with what evidence, and under which controls? When those questions are answered explicitly, tools make agents capable without making them ungovernable.
