Why This Lesson Exists

Every previous lesson in this unit has worked with well-behaved examples: functions that succeed, arguments that arrive in the expected shape, and models that request reasonable things. Production function calling has to handle the cases where none of that holds — a function call that fails partway through, a request that takes too long to complete, and, most importantly, arguments that look syntactically valid but that your code should not blindly trust, because they ultimately originated from a language model's interpretation of a user's request rather than from a source your application fully controls. This lesson treats these as first-class concerns rather than edge cases to patch in later.

The Core Security Principle: Arguments Are Untrusted Input

It's worth stating this plainly and returning to it throughout this lesson: function-call arguments, even though they pass schema validation, are not equivalent to arguments your own code constructed directly. They are the model's interpretation of a user's request, and a user's request can be mistaken, ambiguous, or in a genuinely adversarial case, deliberately crafted to manipulate the model into requesting a function call with harmful arguments (a pattern sometimes called prompt injection when the manipulation comes from content the model reads, such as a document or a web page, rather than the user directly). Schema validation (Lesson 2) constrains the shape of arguments — their types, required fields, allowed values — but it says nothing about whether a schema-valid value is safe or appropriate for your specific function to act on.

# This function call passes schema validation (order_id is a string,
# amount is a number, reason is a string) — but "safe according to the
# schema" and "safe to actually execute" are two different questions.
suspicious_call_arguments = {
    "order_id": "ORD-1",
    "amount": 999999.99,
    "reason": "customer requested",
}

Nothing about this dictionary violates the issue_refund schema from Lesson 4 — every field has the right type, and nothing here is malformed. Whether 999999.99 is a reasonable refund amount for order ORD-1 is a business-logic question the schema cannot answer and was never designed to answer, which is exactly why validation needs to continue inside the function itself, not stop once the schema has passed.

Validating Business Logic Inside the Function

def issue_refund(order_id: str, amount: float, reason: str, order_lookup: dict) -> dict:
    if order_id not in order_lookup:
        return {"success": False, "error": f"Order {order_id} not found."}

    order = order_lookup[order_id]

    if amount > order["total_paid"]:
        return {
            "success": False,
            "error": f"Refund amount {amount} exceeds the order total of {order['total_paid']}.",
        }

    if order["status"] != "delivered":
        return {
            "success": False,
            "error": f"Order {order_id} has status '{order['status']}' and is not eligible for a refund.",
        }

    return {"success": True, "order_id": order_id, "refunded_amount": amount}

orders = {"ORD-1": {"total_paid": 49.99, "status": "delivered"}}
outcome = issue_refund("ORD-1", 999999.99, "customer requested", orders)
print(outcome)  # {'success': False, 'error': 'Refund amount 999999.99 exceeds the order total of 49.99.'}

This mirrors Unit 6's structured-output guidance directly: schema validation and business-logic validation are different checks that serve different purposes, and passing the first does not imply passing the second. Here, checking amount > order["total_paid"] and order["status"] != "delivered" catches exactly the kind of schema-valid-but-substantively-wrong argument the earlier example demonstrated — an amount that is numerically valid but factually incorrect for this specific order, and a status check that prevents a refund on an order that was never actually delivered (perhaps because it was cancelled, or is still in transit). Neither of these checks could have been expressed in the JSON Schema, because they depend on looking up real, current data (order_lookup) that the schema has no access to.

Applying the Principle of Least Privilege

A closely related practice: give each function only the capability it strictly needs, rather than a broad capability that happens to be convenient to implement.

# Overly broad: this function can refund any amount to any order, with no
# built-in ceiling — a bug or a manipulated model could authorize a very
# large, incorrect refund.
def issue_refund_unrestricted(order_id: str, amount: float, reason: str) -> dict:
    process_refund(order_id, amount)  # a stand-in for a real payment API call
    return {"success": True}

# Narrower: caps what a single call can authorize, and requires human
# review above a threshold rather than allowing the model to authorize
# any amount autonomously.
AUTO_APPROVAL_LIMIT = 100.00

def issue_refund_with_limit(order_id: str, amount: float, reason: str, order_lookup: dict) -> dict:
    if amount > AUTO_APPROVAL_LIMIT:
        return {
            "success": False,
            "requires_human_review": True,
            "error": f"Refunds over ${AUTO_APPROVAL_LIMIT} require human approval.",
        }
    # ... the same order_id and status validation as before would go here
    return {"success": True, "order_id": order_id, "refunded_amount": amount}

issue_refund_with_limit() builds in a hard ceiling on what a single, autonomous function call can authorize, routing anything above that ceiling to a requires_human_review outcome rather than an automatic action — a deliberate design choice that limits the blast radius of a single mistaken or manipulated function call, following the same reasoning that leads real payment systems to require human approval above certain thresholds regardless of who or what initiated the request. This is the practical expression of least privilege in a function-calling context: design each function to be capable of exactly what it needs to be capable of, not capable of everything that might theoretically be convenient, especially for functions with real financial, data-modifying, or otherwise consequential side effects.

Handling Timeouts

A function that calls a slow external service (a downstream API, a database under load) needs an explicit timeout, rather than letting a single slow call stall the entire tool-calling loop indefinitely.

import requests

def call_external_service_with_timeout(endpoint: str, payload: dict, timeout_seconds: float = 5.0) -> dict:
    try:
        response = requests.post(endpoint, json=payload, timeout=timeout_seconds)
        response.raise_for_status()
        return {"success": True, "data": response.json()}
    except requests.exceptions.Timeout:
        return {"success": False, "error": f"Request to {endpoint} timed out after {timeout_seconds} seconds."}
    except requests.exceptions.RequestException as e:
        return {"success": False, "error": f"Request to {endpoint} failed: {e}"}

Setting an explicit timeout on the underlying request (rather than relying on whatever default the HTTP library happens to use, which in some libraries is no timeout at all) ensures a single slow or hanging downstream dependency fails predictably and quickly, returning a clear, structured error the calling loop and eventually the model can react to, rather than blocking the entire user-facing interaction for an indefinite period. Catching Timeout specifically alongside the broader RequestException lets the returned error message be more specific and actionable ("timed out" is more informative to a model deciding what to do next than a generic "request failed"), which matters because the model may use this error information to decide whether to retry, try a different approach, or tell the user the service is temporarily unavailable.

Deciding What to Expose in an Error Message

Following Lesson 3's introduction of feeding failures back to the model, it's worth being deliberate about exactly what an error message returned this way contains, since that content may eventually reach an end user through the model's final response.

def query_internal_database_safely(query_params: dict) -> dict:
    try:
        result = run_internal_query(query_params)  # a stand-in for a real database call
        return {"success": True, "data": result}
    except DatabaseConnectionError:
        # Safe: a generic, non-revealing message
        return {"success": False, "error": "The order lookup service is temporarily unavailable. Please try again shortly."}
    except Exception as e:
        # Risky if surfaced directly: str(e) might include a connection string,
        # an internal hostname, a stack trace fragment, or other implementation
        # detail that shouldn't be exposed through a model's response.
        return {"success": False, "error": "An unexpected error occurred while looking up the order."}

The distinction drawn here matters: a specific, safe, actionable message ("temporarily unavailable, try again shortly") is genuinely useful to return, since it lets the model give the user a clear, honest explanation — while a raw exception message from a lower-level library or an internal error is not automatically safe to return verbatim, since it may contain implementation details (a database hostname, an internal file path, a stack trace) that have no business being visible to an end user and were never intended as public-facing text. Deliberately catching specific, anticipated exception types and mapping each to a safe, purpose-written message — rather than passing str(e) straight through for every possible exception — is the practical way to keep this distinction consistent rather than relying on remembering to sanitize every individual error path by hand.

Rate Limiting and Cost Control for Tool-Calling Loops

Since a tool-calling loop can, in principle, run many rounds (bounded only by the max_rounds limit from Lesson 3) and each round involves both a model call and a function execution, it's worth guarding against a loop that technically terminates but still does much more work than a given request actually warrants.

import time

class ToolCallBudget:
    def __init__(self, max_calls: int, max_seconds: float):
        self.max_calls = max_calls
        self.max_seconds = max_seconds
        self.calls_made = 0
        self.start_time = time.monotonic()

    def check_and_increment(self) -> bool:
        elapsed = time.monotonic() - self.start_time
        if self.calls_made >= self.max_calls:
            return False
        if elapsed >= self.max_seconds:
            return False
        self.calls_made += 1
        return True

budget = ToolCallBudget(max_calls=10, max_seconds=30.0)

def dispatch_with_budget(call, available_functions: dict, budget: ToolCallBudget) -> dict:
    if not budget.check_and_increment():
        return {"success": False, "error": "Tool-call budget exceeded for this conversation turn."}
    return dispatch_function_call(call, available_functions)

A ToolCallBudget tracked across an entire user-facing turn (rather than the simpler per-loop max_rounds counter from Lesson 3, which only bounds the number of rounds, not the number of individual calls within a round when multiple tools are requested at once) gives a second, independent layer of protection against a single request consuming disproportionate cost or time — useful in an application where several different tools might be called across several rounds and a hard ceiling on total work per user turn is a reasonable safety and cost-control measure regardless of how the model happens to structure its own calls.

Requiring Explicit Confirmation for Consequential Actions

For a function whose side effects are hard or impossible to undo — issuing a refund, sending an email, deleting a record — a further layer of protection worth building in is requiring an explicit confirmation step between the model deciding to call the function and the function actually executing, rather than executing immediately the moment the model requests it.

PENDING_CONFIRMATION = {}

def request_confirmation(action_id: str, description: str) -> dict:
    PENDING_CONFIRMATION[action_id] = {"description": description, "confirmed": False}
    return {
        "requires_confirmation": True,
        "action_id": action_id,
        "description": description,
        "message": f"This action requires confirmation: {description}",
    }

def confirm_action(action_id: str) -> bool:
    if action_id in PENDING_CONFIRMATION:
        PENDING_CONFIRMATION[action_id]["confirmed"] = True
        return True
    return False

def issue_refund_with_confirmation(order_id: str, amount: float, reason: str, action_id: str) -> dict:
    pending = PENDING_CONFIRMATION.get(action_id)
    if not pending or not pending["confirmed"]:
        return request_confirmation(action_id, f"Refund ${amount} to order {order_id} for: {reason}")
    return {"success": True, "order_id": order_id, "refunded_amount": amount}

The first call to issue_refund_with_confirmation() for a given action_id returns a requires_confirmation result rather than performing the refund — giving the calling application (and, through it, an actual human, whether that's the end user or a support agent operating the tool) a chance to review the specific action described before it happens, with the refund only actually executing once confirm_action() has been called through a separate, deliberate step outside the model's own function-calling flow. This pattern is worth reserving for genuinely consequential, hard-to-reverse actions rather than applying it to every function indiscriminately — a read-only lookup gains nothing from a confirmation step and just adds friction, while an irreversible financial or destructive action benefits meaningfully from a human getting an explicit, final say before it actually happens.

Common Mistakes

Treating schema-valid arguments as automatically safe or correct, skipping business-logic validation inside the function itself and trusting the schema to have already caught every problem it cannot actually catch.

Giving a function broader capability than it strictly needs (an unrestricted refund amount, an unrestricted database query) rather than building in explicit limits and requiring human review above a defined threshold.

Omitting an explicit timeout on calls to external services, allowing a single slow dependency to stall an entire tool-calling interaction indefinitely.

Returning raw exception messages (str(e)) directly as function results, potentially exposing internal implementation details to an end user through the model's eventual response.

Best Practices

Validate business logic inside every function, independent of schema validation, treating "the arguments matched the schema" and "the arguments are safe and correct for this specific call" as two separate questions.

Apply the principle of least privilege to every tool with real side effects, building in explicit limits and routing anything beyond those limits to human review rather than full autonomous execution.

Set explicit, reasonable timeouts on every call to an external service, and return a clear, structured error when a timeout occurs rather than letting the failure propagate unpredictably.

Curate error messages deliberately by catching specific, anticipated exception types and mapping each to a safe, purpose-written message, rather than passing raw exception text through to a result the model (and potentially an end user) will see.

Track a cumulative call budget across an entire user-facing turn, not just a per-round limit, to bound total cost and time regardless of how many tools get called across however many rounds.