Tool calling lets an LLM request data or trigger an external function, but the model should never be treated as an unrestricted execution engine. This guide explains how to design tool schemas, validate arguments, choose between parallel and sequential calls, contain failures, and review an AI workflow on a recurring schedule.
Overview
In a tool-calling workflow, the model decides that it needs an available capability, produces a structured request, and passes that request to application code. Your application then validates the request, applies authorization and business rules, executes the function if permitted, and returns a result to the model or user.
The model can suggest what to call and which values to provide. It should not decide whether an operation is safe, whether a user has permission, or whether a high-impact action should happen without confirmation. Those decisions belong in deterministic application code.
A reliable workflow usually has six stages:
- Define a narrow tool with a clear purpose.
- Describe its inputs using a strict schema.
- Ask the model for a tool call when appropriate.
- Parse and validate the arguments independently.
- Authorize, execute, and monitor the function.
- Return a bounded result and record the outcome.
This separation is the foundation of safe function calling AI. It also makes the system easier to test when a provider changes its SDK, model behavior, supported schema features, or tool-call limits.
A practical tool-definition template
{
"name": "lookup_order_status",
"description": "Return the current status of an order the signed-in user can access.",
"parameters": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "The exact order identifier"
}
},
"required": ["order_id"],
"additionalProperties": false
}
}Keep descriptions factual and operational. A tool called update_customer_record should not also send email, change permissions, or create a payment unless those actions are explicit and separately controlled.
What to track
Track more than whether a model returned valid JSON. Tool reliability depends on the interaction between the prompt, schema, model, application code, external service, and user permissions.
1. Schema and argument quality
- Parse failures: Could the application decode the tool arguments?
- Validation failures: Were required fields missing, types incorrect, or values outside allowed ranges?
- Unknown fields: Did the request include properties your function does not support?
- Semantic errors: Was the format valid but the value nonsensical, such as an end date before a start date?
Use both schema validation and business-rule validation. A schema can confirm that quantity is an integer; application logic must still decide whether zero, negative values, or an unusually large quantity is allowed.
2. Execution and service health
Record tool-call rate, success rate, timeout rate, retry count, and latency by tool. Separate model errors from downstream errors. A valid request that reaches an unavailable CRM is a different problem from a malformed request that never reaches it.
3. Safety and authorization
For every tool, document the required user identity, permitted resources, data sensitivity, and maximum impact. Track rejected authorization checks and approval requests. Avoid putting secrets, access tokens, or private internal instructions in tool descriptions or model-visible results.
For workflows that handle sensitive text, review the PII redaction checklist before sending data to LLM APIs. Tool arguments and tool results can contain personal information even when the original user message does not appear sensitive.
4. Outcome quality
Measure whether the tool helped complete the user’s task, not only whether it ran successfully. Useful review fields include the selected tool, expected tool, argument correctness, result usefulness, user correction, and whether a human had to intervene. A lightweight evaluation set can expose regressions after changing a prompt, schema, model, or validation rule. The LLM evaluation framework provides a useful structure for organizing these checks.
Cadence and checkpoints
Tool calling is not a set-and-forget feature. Establish a review rhythm that matches the risk of the action. A read-only search tool may need a monthly review; a tool that changes records, sends messages, or initiates transactions deserves more frequent operational checks and explicit approval testing.
| Cadence | Checkpoint | Evidence to review |
|---|---|---|
| Per deployment | Contract and safety check | Schema, authorization path, timeout, retry behavior, approval gate |
| Weekly | Operational review | Failures, latency, rejected arguments, downstream incidents |
| Monthly | Quality review | Evaluation cases, user corrections, tool-selection accuracy, cost signals |
| Quarterly | Architecture review | Tool inventory, permissions, unused tools, result payloads, provider changes |
| After an incident | Targeted reassessment | Reproduction, logs, authorization decisions, prompt and schema versions |
Version the tool schema and the prompt that describes when to use it. If a parameter changes from optional to required, treat that as a contract change: update the implementation, test fixtures, model instructions, and rollback plan together. The prompt versioning guide can help keep these artifacts connected.
Parallel versus sequential calls
Use parallel calls when operations are independent and have no ordering requirement. For example, retrieving a user’s profile and notification preferences may be parallel tasks. Use sequential calls when the second request depends on the first result, when actions affect shared state, or when an approval must occur between steps.
| Choose parallel calls when | Choose sequential calls when |
|---|---|
| Requests are read-only and independent | The next argument depends on a prior result |
| Partial results are acceptable | State changes must be ordered |
| Each call has separate limits and failure handling | A human approval or policy check is required |
How to interpret changes
An increase in failed tool calls does not automatically mean the model became worse. First classify the change. A provider or model update may alter tool selection; a schema edit may reject arguments that were previously accepted; a downstream API change may cause timeouts; or a new traffic pattern may expose an unhandled edge case.
Compare changes against a stable evaluation set and a recent production sample. Look for:
- Whether failures cluster around one tool or parameter.
- Whether valid calls are being rejected by an overly narrow schema.
- Whether the model is choosing a tool when a direct answer would be better.
- Whether retries create duplicate side effects.
- Whether tool results are too large, ambiguous, or difficult for the model to use.
Retries require special care. Retrying a read-only request may be reasonable after a transient timeout, but a write operation should use an idempotency key or an equivalent duplicate-protection mechanism. Set a timeout for every external call, cap retry attempts, and return a controlled failure message instead of allowing the model to improvise that an action succeeded.
For high-impact actions, add an approval gate after validation and before execution. Show the user the action, important arguments, and expected consequence. Human-in-the-loop patterns are especially useful when the model can alter records, contact third parties, disclose sensitive data, or trigger irreversible workflows. See the guide to reliable human-in-the-loop AI workflow design for additional patterns.
Also test prompt-injection boundaries. Tool descriptions should not instruct the model to trust content returned from an untrusted webpage, document, or email. Treat retrieved text as data, not as authority. The LLM prompt security checklist covers this distinction in more detail.
When to revisit
Revisit your tool-calling design monthly or quarterly, and sooner whenever a recurring data point changes. Schedule an immediate review after changing a model, provider SDK, system prompt, schema, authorization policy, downstream API, timeout, or retry strategy.
Use this practical review sequence:
- Export recent failures and group them by tool, error type, and workflow step.
- Run a fixed test set covering valid, missing, extra, boundary, and malicious arguments.
- Verify authorization with users who should be allowed and denied.
- Test timeouts, duplicate requests, partial failures, and unavailable services.
- Review whether tool results expose unnecessary data or exceed the context budget.
- Compare the current version with the last known-good prompt, schema, and evaluation results.
- Record the decision: keep, revise, restrict, deprecate, or replace the tool.
When a tool repeatedly fails, do not solve every problem by adding more prompt text. Narrow the tool’s scope, improve the schema, move critical rules into code, or split one broad function into smaller operations. Reliable tool calling comes from clear contracts and observable controls—not from assuming the LLM will always infer the right boundary.
Before deployment, confirm that every tool has an owner, a documented purpose, validation rules, authorization logic, timeout, failure response, audit trail, and rollback path. Then put the next review date on the engineering calendar. That small habit keeps an AI function-calling workflow aligned with its real users, services, and risk profile as the surrounding system changes.