Microsoft AI-103: Tool Schemas for AI Agents
A tool schema is the contract between an AI agent and the system it is allowed to call: it constrains arguments, explains what the tool does, and supports independent server-side authorization. A clear schema narrows the model’s choices and makes backend validation predictable; vague descriptions force the model to infer hidden business rules. In Microsoft AI Agents, Foundry function tools use names, descriptions, and JSON Schema parameters to describe permitted operations. That interface should be precise without pretending a model can authorize itself.
Microsoft’s current function-calling guidance emphasizes clear function descriptions, correct JSON types, required properties, and strict schema validation where supported. Structured outputs can enforce JSON Schema more strongly than older JSON-only modes, and Foundry agents can return multiple function calls in one response. Those capabilities improve reliability, but the application still has to execute tools, validate results, handle errors, and return tool output to the model so the conversation can continue.
Give every tool one clear responsibility
A tool named manage_customer that can search, edit, refund, suspend, and message a customer creates unnecessary ambiguity. Split capabilities around stable business actions such as get_customer_profile, create_refund_request, or send_case_update. Narrow tools make it easier for the model to select correctly, for the backend to authorize specifically, and for operators to understand what a tool call means in traces.
An agent becomes more reliable when it composes several explicit capabilities rather than invoking one oversized function with dozens of modes. In multi-step agent workflows, tool boundaries should reflect real operational boundaries instead of simply mirroring whichever internal API happened to exist first.
Write descriptions that explain intent and constraints, not implementation trivia
The tool description should tell the model when the tool is appropriate, what it does, and any important preconditions. Avoid internal service names that mean nothing to the model, and avoid vague descriptions such as “handles orders.” Parameter descriptions should state units, formats, accepted identifiers, and semantic meaning. Examples can help when a field is commonly confused with another field, but they should not replace validation.
A description saying “only use this for the current user” guides the model but does not enforce access control. The tool executor must derive or validate the caller’s identity server-side and reject requests outside that person’s authority. These are API security responsibilities, not guarantees supplied by the schema.
Use JSON Schema to constrain the model’s argument space
Types, required arrays, enums, minimums, maximums, and object structure can eliminate entire classes of malformed calls. Use strings for identifiers that may contain leading zeros, enums for small closed choices, and nested objects only when the business concept is genuinely nested. Make optional fields truly optional rather than requiring the model to invent empty values to satisfy the schema.
Changing a tool contract can break an agent even when the backend still accepts older requests. The same compatibility problem appears in schema evolution: version important changes, preserve compatibility where practical, and test older agent prompts against the new schema before deployment.
Names should remain stable once the tool is widely deployed because prompts, evaluations, and telemetry often reference them. If a function must be replaced, introduce the new tool explicitly and retire the old one through a controlled migration. Quietly changing meaning behind the same name makes historical traces misleading and can cause a model to apply learned calling patterns to a different operation.
Use strict structured outputs where correctness matters
Microsoft’s structured-output support can enforce a supplied JSON Schema for function calling, reducing the gap between “valid JSON” and “valid business shape.” Strictness is especially useful when downstream code assumes fields are present or when an invalid value would trigger expensive recovery logic. It should be paired with backend validation because a structurally valid request can still be unauthorized, stale, or semantically wrong.
Strict mode constrains the shape of a function call only when the selected model and endpoint support that option. For a JSON Schema tool, define allowed properties, types, required fields, and enumeration values explicitly; supported strict schemas can reject extra keys using additionalProperties: false. Test four negative cases: a missing required identifier, an unexpected property, an enum outside the allowed values, and a syntactically valid request for another customer’s record. The first three probe schema behavior; the fourth must still be denied by server-side identity and business rules. A schema can be valid while a requested action is unsafe. With Microsoft Foundry, the application executes the requested function and submits its output; registering a tool definition does not by itself authorize a transaction.
Release tests should distinguish schema adherence from semantic correctness. A useful generative AI evaluation pipeline verifies that tool calls conform to the contract and separately checks whether the agent chose the appropriate capability with arguments supported by the user’s intent.
Design write tools for confirmation, idempotency, and safe retries
Read operations and write operations should not share identical risk assumptions. For consequential writes, include fields that let the backend detect duplicate attempts, validate expected state, or require a confirmation token. Network failures can leave the agent uncertain whether an action succeeded, so a retry must not create a second order, payment, ticket, or deletion.
For consequential actions, design agent access and approval boundaries around the specific request the executor will perform. Approval is stronger when the intended action is immutable and verifiable, rather than a vague conversational “yes” followed by freshly generated parameters.
Return structured errors the agent can reason about safely
Tool failures should distinguish invalid input, authorization denial, not found, conflict, throttling, transient dependency failure, and permanent business rejection. Do not return stack traces or database errors to the model and hope it interprets them correctly. A compact error code plus safe explanation and retry guidance gives the agent enough information to choose the next step.
Track validation failures and authorization denials separately. In agent analytics and monitoring, a high schema-validation failure rate suggests a clearer schema or description; a spike in access denials after an agent update calls for examining tool selection and identity propagation.
Handle multiple and parallel tool calls deliberately
Foundry agents can produce several function calls in one response when the model believes multiple actions are needed. Parallel execution can reduce latency for independent reads, but it is unsafe when calls depend on each other or create side effects that must be ordered. The application should understand dependency and conflict rather than blindly executing every returned call concurrently.
Tools are steps in a workflow, not isolated API requests. In agentic orchestration, a call that creates an identifier another call needs must finish first, whereas independent lookups can run in parallel without changing the outcome.
Keep secrets and hidden policy out of tool descriptions
Tool schemas are often visible to the model and can appear in traces or debugging interfaces. Do not place API keys, internal credentials, sensitive business rules, or confidential endpoint details in descriptions. Use server-side connections and managed identity where possible, and reference abstract resource names rather than embedding secrets in prompt-visible metadata.
Keep authority outside the model’s prompt-visible context. Autonomous agent security depends on backend enforcement: the agent should understand the permitted effect of a tool, but no prompt text should let it bypass authorization. That also limits the effect of a prompt-injection attempt.
When a schema changes, test that the current agent can call it and that the executor handles the current model’s behavior. Track tool version, agent version, and schema version in telemetry. For widely reused tools, publish migration guidance and deprecation timelines so one team’s improvement does not silently break several agents.
Promote tool contracts through the same development, test and production stages as prompts and models. Good agent lifecycle management includes contract tests for valid calls, invalid inputs, authorization failures and tool-result handling before approving a new version.
Keep a machine-readable schema and a human-readable contract together. Engineers need to understand side effects, authorization expectations, latency, and retry behavior that JSON Schema cannot fully express. The model needs concise field descriptions; reviewers need the broader operating semantics. Maintaining both prevents documentation from drifting away from the actual callable interface.
Treat the schema as a reliability boundary, not a magic safety layer
A precise schema helps the model form better requests and makes validation more deterministic, but it cannot decide whether a user is entitled to perform the action or whether the action is sensible in the current business state. Keep identity, authorization, business validation, concurrency control, and audit logging in the executor and downstream services.
Microsoft Foundry provides function calling and structured-output capabilities that can make agent tools more dependable. The strongest designs use those features to narrow ambiguity while preserving conventional software controls around every side effect. Tool schemas should make the safe path easy for the model and the unsafe path impossible for the backend.
Schema design should also account for localization and formatting. Dates, currencies, phone numbers, measurements, and user-entered names can be represented differently across regions. Prefer canonical machine formats in the tool contract and let the conversational layer handle presentation. This reduces ambiguity and prevents a locale-specific string from being interpreted differently by the model and the backend.
For tools that accept free-form text, keep that freedom narrow. A short reason or note field may be appropriate, but entire SQL statements, shell commands, or arbitrary URLs dramatically expand the execution surface. When flexible input is unavoidable, route it through a dedicated validation or sandbox layer rather than treating the JSON schema as sufficient protection.