Function Calling & Tool Use

Function calling does not let a model run a function directly. The model emits a structured request; the application validates arguments, checks policy, executes the tool, and returns the result. That boundary determines whether the system is controllable.

---

The complete data path

user request
  → model decides whether a tool is needed
  → tool name + arguments + call ID
  → application validates schema, policy, and business rules
  → tool executes inside a boundary
  → application returns output for that call ID
  → model answers or requests another tool

Treat model output as an untrusted execution proposal, not an authorised command.

---

When tool calling is useful

For a task with two or three deterministic steps, ordinary application code may be enough. Do not add an autonomous loop only to make the system look agentic.

---

A schema should express business boundaries

{
	"type": "function",
	"name": "create_support_ticket",
	"description": "Create a ticket after the customer and issue are identified. Do not use for status lookup.",
	"parameters": {
		"type": "object",
		"properties": {
			"customer_id": {
				"type": "string",
				"description": "Verified internal customer ID"
			},
			"category": {
				"type": "string",
				"enum": ["billing", "account", "technical"]
			},
			"summary": {
				"type": "string",
				"minLength": 10,
				"maxLength": 500
			},
			"evidence_ids": {
				"type": "array",
				"items": { "type": "string" },
				"minItems": 1
			}
		},
		"required": ["customer_id", "category", "summary", "evidence_ids"],
		"additionalProperties": false
	}
}

A useful description says when to use the tool and when not to use it. Put enums, length, and format constraints in the schema. Keep permissions, balances, and state-machine rules in server-side validation.

---

A controlled executor

async function executeToolCall(call: ToolCall, actor: Actor) {
	const tool = registry.get(call.name);
	if (!tool) return toolError(call.id, 'TOOL_NOT_AVAILABLE');

	const parsed = tool.schema.safeParse(call.arguments);
	if (!parsed.success) {
		return toolError(call.id, 'INVALID_ARGUMENTS', parsed.error.issues);
	}

	const policy = await authorize(actor, call.name, parsed.data);
	if (!policy.allowed) return toolError(call.id, 'FORBIDDEN');

	if (policy.requiresApproval) {
		return toolPendingApproval(call.id, await createApproval(call, actor));
	}

	try {
		const result = await withTimeout(
			tool.execute(parsed.data, {
				idempotencyKey: `${actor.taskId}:${call.id}`
			}),
			tool.timeoutMs
		);
		return toolSuccess(call.id, sanitizeForModel(result));
	} catch (error) {
		return mapToolError(call.id, error);
	}
}

Return concise field errors to the model for one repair attempt. Do not place stack traces, secrets, or internal network details in model-visible context.

---

Errors should drive a safe next step

“Tool failed” is not diagnostic. Use stable error codes, brief messages, and internal-only raw exceptions.

---

Separate reads from writes

Do not create one manage_customer tool for lookup, update, and deletion. Split it into:

• get_customer_profile
• update_customer_contact
• request_customer_deletion

This allows dynamic tool exposure by user state. Before identity verification, expose only reads. Load updates after verification. Always require approval for deletion.

Mutation tools also need an idempotency key, dry-run diff, provider request ID, rollback semantics, and a final state read-back.

---

Parallel calls are not always faster

Inventory queries across three independent warehouses can run in parallel. Looking up an order and then using its payment ID must be sequential. Before parallelising, confirm:

• Calls have no data dependency.
• The tool and downstream service support the concurrency.
• Result order does not change business meaning.
• Partial failure has a defined merge policy.

Do not ask the model to generate dozens of parallel mutations. Let code control batch size, rate, idempotency, and recovery.

---

Security and data boundaries

Web pages and documents returned by tools are data, not higher-priority instructions. An injected sentence cannot grant itself refund permission.

---

Evaluate more than schema compliance

Your golden set should cover correct tool use, direct answers without tools, missing information, similar tool names, business-rule rejection, timeouts, rate limits, prompt injection, and replayed mutations.

Practice task

Implement order lookup, ticket creation, and refund request tools:

1. State inclusion and exclusion conditions for each tool.
2. Add amount, reason, approval ID, and evidence IDs to the refund schema.
3. Simulate missing fields, forbidden access, 429, and provider timeout.
4. Replay one refund call and confirm only one side effect occurs.
5. Record call ID, redacted arguments, latency, error code, and read-back evidence.

Definition of done

• The model proposes calls; the application retains execution authority.
• Schema and business rules are validated separately.
• Reads and writes are separated; risky writes require approval.
• Every tool has a timeout, stable error codes, and retry limit.
• Mutations are idempotent and verified against real state.

Related reading

• Tool Design Principles
• Advanced Tool Use
• MCP Best Practices
• Advanced Agent Systems

Official references

• https://developers.openai.com/api/docs/guides/function-calling
• https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools