Reliable LLM tool use requires more than giving a model a function name. This guide explains how to design tool schemas, validate arguments, manage repeated or malformed calls, and review provider changes so an AI integration remains safe and maintainable.
Overview
Function calling, also called tool use, lets an LLM request an operation from your application instead of attempting to complete that operation in text. The model may ask to retrieve an order, search a knowledge base, calculate a value, create a ticket, or call another API. Your server—not the model—executes the operation and returns the result to the conversation.
A dependable implementation separates four responsibilities:
- Decision: the model chooses whether a tool is relevant.
- Validation: your application checks the requested tool and its arguments.
- Execution: a controlled service performs the operation with explicit permissions.
- Recovery: the application handles invalid arguments, tool errors, timeouts, and repeated requests.
Tool calling should therefore be treated as an API integration pattern, not as a permission system. A valid JSON argument does not make an operation safe. Every tool still needs authentication, authorization, input limits, logging, and, where appropriate, human approval.
The exact request and response syntax differs between providers and SDK versions. In general, one provider may expose tools under a tools array with a function and JSON Schema, while another may use a tool definition with an input_schema or a function-declaration object. Treat the provider documentation and your installed SDK as the source of truth, and keep your internal tool representation provider-neutral.
What to track
1. Tool schemas and boundaries
Define each tool as a narrow operation with a clear purpose. Avoid a general-purpose tool such as run_sql, execute_code, or send_any_request when a smaller operation can express the required capability.
A reusable schema can look like this:
{
"name": "lookup_order",
"description": "Retrieve the status of an order the authenticated user may access.",
"parameters": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "The order identifier supplied by the user."
}
},
"required": ["order_id"],
"additionalProperties": false
}
}Use descriptions to explain meaning and constraints, not to hide business logic. Put important authorization rules in application code. Schema restrictions vary by provider and model, so test whether your chosen integration supports the keywords you depend on. If a constraint is not reliably enforced by the model, enforce it again in your validator.
2. Validation rules
Validate the tool name against an allowlist before parsing arguments. Then validate the arguments against a server-side schema. Useful checks include:
- Required fields are present and have the expected types.
- Strings have length limits and acceptable formats.
- Numbers fall within safe minimum and maximum values.
- Enumerated values are restricted to known options.
- Unexpected properties are rejected or deliberately ignored.
- Identifiers belong to the user, tenant, or conversation context.
- Free-text fields are bounded to prevent excessive downstream input.
Do not rely on a system prompt to enforce these rules. Prompt instructions can guide model behavior, but the application must enforce security and data-access boundaries.
3. Provider syntax and behavior
Before adopting a model or changing an SDK, record the following in an integration note:
| Area | What to compare | Why it matters |
|---|---|---|
| Tool declaration | Field names, schema shape, and description limits | A schema that works with one API may need an adapter for another. |
| Tool request | How tool name, identifier, and arguments are returned | Your dispatcher must extract the correct fields and preserve call identity. |
| Tool result | How results are added back to the conversation | Incorrect message roles or identifiers can break the next model turn. |
| Parallel calls | Whether multiple tools may be requested in one response | Parallel execution can reduce latency but increases coordination and risk. |
| Structured output | Supported schema restrictions and refusal or failure behavior | Strict output settings do not replace server-side validation. |
| Token use | Schema, descriptions, arguments, and results included in context | Large tool definitions can reduce the space available for useful conversation. |
Common provider patterns include function tools in one API, tools with an input schema in another, and function declarations nested inside generation configuration in a third. Build a small adapter for each provider rather than spreading provider-specific conditionals throughout business logic.
4. Execution and audit data
Record a correlation ID, conversation or request ID, authenticated principal, model identifier, tool name, validated arguments after sensitive fields are redacted, start and end times, outcome, and error category. Keep secrets, access tokens, and unnecessary personal data out of prompts and logs. Audit records should explain what the system attempted, not merely what the model said.
Cadence and checkpoints
Review tool integrations on a quarterly schedule at minimum, and sooner when a provider releases a model, API, or SDK update that affects tool use. A lightweight review can follow this sequence:
- Contract check: compare the provider's current request and response examples with your adapter.
- Schema check: test required fields, rejected fields, long strings, invalid enums, and empty values.
- Conversation check: verify the complete loop: user request, model tool call, server execution, tool result, and final response.
- Failure check: simulate timeouts, authorization failures, malformed JSON, unknown tools, duplicate calls, and downstream errors.
- Safety check: confirm that tools cannot cross tenant boundaries or perform high-impact actions without required approval.
- Cost and latency check: inspect schema size, result size, number of model turns, and execution time.
Also review after adding a tool, renaming an argument, changing a permission, switching model families, changing the model's context budget, or upgrading an SDK. Keep a small regression set of ordinary requests, ambiguous requests, adversarial inputs, and requests that should not call a tool. This connects tool testing to the broader practices in the LLM evaluation guide and the prompt testing framework.
How to interpret changes
A change in tool-call rate is not automatically an improvement. More calls may indicate that the model is overusing a tool, while fewer calls may mean it is answering from incomplete context instead of retrieving required data. Review representative traces and classify outcomes rather than watching a single aggregate metric.
Useful categories include:
- Correct direct answer: no tool was needed.
- Correct tool selection: the model chose the appropriate capability.
- Correct arguments: values passed validation and matched user intent.
- Execution failure: the downstream service failed or timed out.
- Recovery failure: the model repeated an invalid call or produced an unsupported fallback.
- Permission failure: the request exceeded the user's authority and was correctly blocked.
For malformed arguments, return a compact, non-sensitive error that identifies the fields requiring correction. Give the model a bounded opportunity to repair the call, then stop and ask the user for clarification or report the failure. Do not retry indefinitely. Use an idempotency key for operations that create, charge, publish, delete, or otherwise change state.
Repeated calls need explicit handling. Set a maximum number of tool rounds per request, detect identical tool name-and-argument combinations, and distinguish a retryable timeout from a permanent validation or permission error. Parallel calls should be enabled only when the operations are independent and the application can safely reconcile partial success. For state-changing tools, sequential execution or an approval step may be more appropriate.
Prompt design still matters. Tool descriptions should state when a tool is appropriate, what it cannot do, and which values must come from the user or application context. However, prompt instructions are one layer of defense. For risks involving untrusted retrieved content or user-supplied instructions, review the prompt injection defense checklist.
When to revisit
Use this article as a recurring review checklist whenever your tool surface or model behavior changes. At each monthly or quarterly checkpoint, select a sample of real traces, run the regression suite, and compare validation failures, repeated calls, execution errors, latency, and unauthorized-request blocks with the previous review. Investigate changes rather than optimizing for tool-call volume alone.
Before production deployment, confirm these basics:
- Every tool has a narrow purpose, an owner, and a versioned schema.
- Tool names and arguments are validated server-side.
- Authentication and authorization are independent of model output.
- Destructive or costly actions have confirmation or approval controls.
- Malformed calls, timeouts, duplicate calls, and provider errors have bounded recovery paths.
- Logs contain correlation data without exposing secrets or unnecessary personal information.
- Provider-specific syntax is isolated behind an adapter and tested after SDK updates.
- Regression cases cover both valid tool use and cases where the correct action is no tool call.
Finally, maintain a short change log for model versions, schema revisions, provider behavior, and test results. That record makes debugging easier when an integration changes unexpectedly and provides a practical trigger for the next review. Related implementation guidance is available in the LLM API errors guide and the structured-output prompts guide.