LLM Tool Calling Tutorial: Build Reliable Function-Calling Workflows
tool callingfunction callingLLM developmentAI agentsAPI integration

LLM Tool Calling Tutorial: Build Reliable Function-Calling Workflows

SSupervised Online Editorial Team
2026-11-09
7 min read

Learn a provider-neutral workflow for safer LLM tool calling, from schemas and validation to execution boundaries, errors, confirmation, and testing.

Tool calling lets an LLM application request defined actions—such as looking up an order, querying a database, or creating a draft—without giving the model direct control of your systems. This tutorial presents a provider-neutral workflow for designing tool schemas, validating arguments, enforcing execution boundaries, handling failures, requesting confirmation, and formatting results safely. Use the checklists whenever you add a tool, change an API contract, or troubleshoot unreliable function calls.

Overview

In a tool-calling workflow, the model does not normally execute a function itself. Instead, it receives a list of available tools and decides whether one is relevant. If it selects a tool, it produces a structured request containing the tool name and arguments. Your application then validates that request, runs the corresponding server-side function, and sends a controlled result back to the model. The model can use that result to produce a user-facing response or request another tool.

A reliable implementation separates these responsibilities:

  1. Model decision: The LLM proposes whether a tool is needed and which arguments to use.
  2. Application validation: Your code checks the tool name, argument types, allowed values, permissions, and business rules.
  3. Tool execution: A trusted application component calls the API, database, or internal service.
  4. Result handling: The application returns a constrained result that the model can interpret without exposing unnecessary data.
  5. User response: The model explains the outcome, asks for missing information, or reports a failure clearly.

This division is important in LLM app development. A model-generated tool request is an untrusted input, even when the model is operating inside your own application. Treat it like any other external request: parse it, validate it, authorize it, log it, and fail safely.

A provider-neutral capability comparison

Different model providers and SDKs expose tool calling through different request formats and feature names. Before implementation, compare capabilities rather than assuming that one integration pattern works everywhere.

CapabilityWhat to verifyWhy it matters
Tool declarationHow tools, descriptions, and JSON schemas are suppliedDetermines how much structure the model sees before it responds
Tool selectionWhether the model can choose automatically, be required to call a tool, or be prevented from calling oneSupports predictable workflows and controlled fallbacks
Schema supportSupported types, enums, required fields, nested objects, arrays, and constraintsReduces malformed or ambiguous arguments
Multiple callsWhether one response can contain several tool requestsAffects orchestration, ordering, and rate-limit planning
Conversation stateHow tool requests and tool results are represented in the next model turnPrevents broken message histories and mismatched results
Streaming behaviorWhen tool names and arguments become available during streamingHelps you decide when to buffer, validate, and execute

Checklist by scenario

Scenario 1: Adding a read-only tool

Read-only tools include product searches, documentation retrieval, account lookups, and reporting queries. They still need controls, but their consequences are generally easier to contain.

  • Define one narrow purpose instead of combining unrelated lookups.
  • Give the tool a specific name, such as search_orders, rather than a vague name such as helper.
  • Describe each argument in terms the model can distinguish from similar fields.
  • Mark genuinely required arguments as required and reject unknown arguments where practical.
  • Apply authentication, authorization, tenant, and row-level access checks in application code.
  • Limit result size and return only fields needed for the next decision.
  • Return an explicit empty result when nothing matches; do not make the model infer that a missing field means no data.

Scenario 2: Adding a write or side-effecting tool

Creating records, sending messages, changing settings, issuing refunds, or deleting data requires a stricter boundary. The model may prepare an action, but your application should decide whether it is allowed to happen.

  • Separate preview or draft operations from committed operations.
  • Require confirmation for actions that are consequential, difficult to reverse, externally visible, or financially significant.
  • Use an idempotency key or equivalent duplicate protection when an operation could be retried.
  • Re-check permissions and current state immediately before execution.
  • Record who initiated the action, which tool was selected, the validated arguments, and the outcome.
  • Return a stable operation identifier so the user and application can check status later.

Scenario 3: Building a multi-tool agent workflow

When an application has several tools, start with an explicit orchestration policy rather than allowing unrestricted tool use. Define which tools can follow one another, how many calls are allowed in one task, and what happens when a prerequisite fails.

  • Group tools by task or permission boundary.
  • Set a maximum number of model-tool turns and an execution timeout.
  • Prevent a tool from receiving secrets, hidden instructions, or unrelated conversation data.
  • Require the model to explain missing inputs instead of guessing them.
  • Use structured status values such as success, not_found, needs_confirmation, and error.
  • Test loops, repeated calls, conflicting results, and partial completion.

For broader workflow design, see the AI workflow automation guide for developers. If tools can receive untrusted retrieved content, also review the prompt injection prevention checklist.

Reusable tool definition template

Keep the definition short enough to be unambiguous and precise enough to constrain arguments. The exact wrapper varies by provider, but the conceptual structure can remain stable:

{
  "name": "lookup_order",
  "description": "Find an order visible to the authenticated user by order ID.",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "The exact order identifier supplied by the user."
      }
    },
    "required": ["order_id"],
    "additionalProperties": false
  }
}

The description should state what the tool does, what it does not do, and any important input interpretation. Do not rely on the schema alone for security; authorization and business validation belong in the execution layer.

What to double-check

Argument validation

Parse the model output with a strict schema validator. Check types, ranges, formats, enums, string lengths, dates, identifiers, and cross-field relationships. For example, a date range may require an end date that is not earlier than the start date. Normalize harmless formatting differences, but reject values that change meaning.

Execution boundaries

Map approved tool names to server-side functions through an allowlist. Never execute a function based on a model-provided name without checking that it is registered. Keep credentials, database connections, and internal service details outside the model context. Apply least-privilege permissions for each tool instead of sharing one broad application credential.

Error handling and retries

Distinguish validation errors, authorization failures, not-found results, temporary service failures, and timeouts. A retry may be appropriate for a temporary failure, but it should be bounded and safe. Do not automatically retry a side effect unless duplicate execution is controlled. Give the model a concise machine-readable error and a user-safe explanation path.

Result formatting

Return structured results with a predictable shape. Include the facts needed for the next step, not an entire database response. If a result contains user-generated text or retrieved documents, label it as data rather than instructions. This supports safer grounding and makes it easier to inspect what influenced the final response. For related fact-checking practices, see this workflow for detecting hallucinations in LLM answers.

Testing and observability

Build test cases for clear requests, ambiguous requests, missing arguments, invalid values, unauthorized access, empty results, tool timeouts, malformed model output, and prompt-injection attempts. Track tool selection accuracy, validation failures, execution latency, retry counts, and user-confirmation drop-off. A prompt evaluation framework can help you compare changes systematically; see the LLM prompt evaluation framework for a testing approach.

Common mistakes

  • Making tools too broad: A single tool that searches, edits, deletes, and sends messages is difficult to authorize and test. Prefer narrow operations.
  • Trusting the schema as security: A valid argument can still be unauthorized or unsafe. Re-check identity, ownership, limits, and current state on the server.
  • Letting the model invent missing values: Require clarification for identifiers, dates, recipients, or quantities that affect the action.
  • Returning raw exceptions: Stack traces and internal service details can confuse users and expose implementation information. Log them privately and return controlled errors.
  • Ignoring duplicate execution: Timeouts can make the application unsure whether a side effect completed. Use idempotency and status checks where possible.
  • Testing only the happy path: Reliable AI tool use depends on failure cases, not just successful demos.
  • Changing a tool contract silently: Renaming arguments or changing result shapes can break prompts, validators, and downstream code. Version or migrate contracts deliberately.

Tool calling also depends on the model you select and the surrounding application architecture. Revisit this practical LLM selection comparison when latency, context handling, structured output, or tool-use behavior becomes a deciding factor.

When to revisit

Use this checklist before releasing a new tool and whenever the workflow changes. Revisit it in particular when:

  • A model, SDK, API version, or tool-calling format changes.
  • You add a write operation, new permission scope, or external integration.
  • An API contract changes its required fields, response shape, or error behavior.
  • Users report repeated calls, incorrect arguments, unexpected actions, or unclear failures.
  • Seasonal planning cycles change volumes, business rules, approval requirements, or data sources.
  • You introduce retrieval, long-running jobs, streaming, parallel calls, or human approval steps.

Before release, confirm that every tool has a narrow purpose, an explicit schema, server-side authorization, bounded execution, safe error handling, and test coverage for failure cases. Then run a small end-to-end review: submit a normal request, an ambiguous request, an unauthorized request, and a request that should require confirmation. Inspect the model request, the validated arguments, the executed action, the returned result, and the final response. Repeat that review whenever the underlying tools or workflow change.

Related Topics

#tool calling#function calling#LLM development#AI agents#API integration
S

Supervised Online Editorial Team

AI Development Editors

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.