← Autonomous AI Agents
0/15 complete

Module 01 · Agent Fundamentals

Tool Use and Function Calling Explained Simply

25 minfocused lesson5practical steps4grounded questions3source links
Open lesson + course map

On this lesson

Course outline

Tool use lets a model request a named operation with structured arguments. The application—not the model—must validate the request, authorize the caller, execute the tool, and return a controlled result. A function schema improves structure; it does not prove that an action is safe or correct.

After this lesson, you can design a typed tool contract and a secure execution wrapper.

// concept

Write the Contract

Example read-only inventory tool:

// json10 lines
{
  "name": "get_inventory",
  "description": "Return current sellable quantity for one approved SKU.",
  "input": {
    "type": "object",
    "properties": { "sku": { "type": "string", "pattern": "^[A-Z0-9-]{2,20}$" } },
    "required": ["sku"],
    "additionalProperties": false
  }
}

Define actor, permission, rate limit, timeout, idempotency behavior, result schema, logged fields, redaction, and error classes outside the prompt.

// concept

Separate Selection From Execution

Use this path:

// prompt — copy me9 lines
model proposes call
→ parse strict JSON
→ validate schema
→ authenticate actor
→ authorize exact resource/action
→ require approval if needed
→ execute with timeout/idempotency
→ redact result
→ append observation

Never concatenate model arguments into a shell command or SQL string. Parameterize database queries, allowlist command operations, resolve file paths inside an approved root, and reject unknown fields.

// concept

Make Errors Machine-Readable

Return controlled classes:

// json1 line
{ "ok": false, "error": { "code": "NOT_FOUND", "retryable": false } }

Do not expose stack traces, tokens, private rows, or internal filesystem paths. A timeout may be retryable; an authorization failure is not. The agent must not “solve” forbidden access by choosing another tool.

// worked_example

Worked Example

A Lahore distributor builds create_quote_draft. Inputs are approved customer reference, SKU list, quantities, and validity days. Server code retrieves current prices, computes PKR totals with decimal-safe logic, and creates a DRAFT only. The model cannot supply a total or customer discount.

The wrapper rejects an unknown SKU, quantity over the policy limit, expired customer authorization, and additional JSON fields. Repeating the same logical request uses one idempotency key and returns the existing draft. Publishing or sending the quote is a separate approved tool.

// failure_cases

Failure Cases to Diagnose

7 cases to diagnose

  • Tool description is the only permission control

    enforce server-side authorization.

  • Model supplies price or paid status

    retrieve and calculate from authoritative systems.

  • Arbitrary URL fetch creates SSRF

    allowlist destinations and block private networks.

  • File path escapes the workspace

    resolve and verify the final canonical path.

  • Retry duplicates an order

    require stable idempotency.

  • Tool returns entire customer record

    minimize and redact output.

  • One super-tool does everything

    split read, prepare, approve, and execute operations.

// pakistan_angle

Pakistan Angle

For payment, wallet, bank, courier, and tax integrations, treat the provider documentation and server response as authoritative. Never ask a model to infer settlement from a screenshot or compose a request containing a PIN, OTP, banking password, or unnecessary CNIC data.

When local services are slow or unavailable, return TEMPORARY_UNAVAILABLE with a case reference and bounded retry. Do not silently switch to an unofficial scraping endpoint or personal employee account. That creates fragile operations and privacy exposure.

// hands_on

Hands-On Exercise

5 steps

  1. Define a read tool and a draft-creation tool in JSON Schema.

  2. Add auth, authorization, timeout, rate, and idempotency rules.

  3. Define success and four error result shapes.

  4. Test injection, unknown fields, resource escape, duplicate call, and secret redaction.

  5. Review whether each write can be split into prepare and approve.

// completion_rubric

Completion Rubric

6 checks — tick as you verify

0/6

// sources

Sources

3 official sources — check every claim yourself

// check_yourself

Check yourself

4 questions · answers and options are taken word-for-word from this course

0/4

  1. 1 / 4 · diagnose

    Your work shows this failure mode: “Tool description is the only permission control.” What does the lesson tell you to do about it?