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.
Write the Contract
Example read-only inventory tool:
{
"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.
Separate Selection From Execution
Use this path:
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.
Make Errors Machine-Readable
Return controlled classes:
{ "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
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 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
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 Exercise
- Define a read tool and a draft-creation tool in JSON Schema.
- Add auth, authorization, timeout, rate, and idempotency rules.
- Define success and four error result shapes.
- Test injection, unknown fields, resource escape, duplicate call, and secret redaction.
- Review whether each write can be split into prepare and approve.
Done means: malformed, unauthorized, duplicated, or adversarial arguments cannot create an uncontrolled side effect.
Completion Rubric
- Inputs and outputs use strict schemas.
- Authentication and authorization run outside the model.
- Effects use timeouts and idempotency.
- Errors are controlled and non-secret.
- Resources and destinations are allowlisted.
- Consequential tools separate prepare from execute.
Sources
Key takeaway: a tool call is an untrusted proposal until application code validates, authorizes, executes, deduplicates, and safely returns it.