Example (OpenAI client + tool definition):

import OpenAI from "openai";
const client = new OpenAI();

const tools = [
  {
    type: "function",
    name: "get_weather",
    description: "Get current weather for a location",
    parameters: {
      type: "object",
      properties: {
        location: { type: "string" },
        units: { type: "string", enum: ["celsius","fahrenheit"], default: "fahrenheit" },
      },
      required: ["location"],
    },
  },
];

const res = await client.responses.create({ model: "gpt-5.4", tools, input: [{ role: "user", content: "What's the weather in Paris?" }] });
// If the response contains a function_call, execute, then return function_call_output with the same call_id

Notes:

• Always validate tool names and schemas before executing anything returned by the model.
• If you run tools in parallel, ensure the model's continuation can disambiguate results (call_id matching) — do not assume implicit ordering.

Anthropic: tool_use / tool_result and programmatic tool calling

• Claude exposes a tool_use / tool_result pattern: the model emits tool_use blocks (requests), your app executes the requested action, and you return tool_result blocks containing the results and the original tool_use_id to continue the conversation (Anthropic Tool Use docs).
• Anthropic supports programmatic tool calling where Claude can write and execute code inside a sandboxed code_execution container and call your tools directly from that code. This reduces round trips and token/context usage for complex multi-tool workflows (Anthropic programmatic tool calling docs). Typical flow:
  1. Claude generates code that calls client-callable tools
  2. The code runs in a sandbox (code_execution)
  3. Each tool invocation pauses execution and the API returns a tool_use block
  4. Your system executes the tool and returns a tool_result referencing the original tool_use_id
• Use allowed_callers to scope which in-container runtimes (e.g. code_execution) may invoke a tool. Use strict: true on tool schemas to require exact schema conformance and reduce post-processing.

Example (conceptual):

• Provide a query_database tool with an input_schema; mark allowed_callers: ["code_execution_20260120"] so only the in-container script can call it.
• When Claude runs aggregated queries, it can run a single script and return only the filtered summary to the model instead of streaming large raw datasets into the context.

Cross-provider abstraction points

• Call/response pairing: OpenAI uses function_call / function_call_output with call_id; Anthropic uses tool_use / tool_result with tool_use_id. Preserve and round-trip these ids in your orchestration loops.
• Schema enforcement: Prefer Zod or JSON Schema for tool inputs/outputs. Anthropic supports strict: true. OpenAI Responses and many front-end SDKs (Vercel AI SDK v6+) consume JSON Schema/Zod to improve LLM-to-tool mapping.
• Server-run vs client-run tools: Some provider-run tools return results directly (server-run); others return structured requests for your app to execute (client-run). Handle both patterns and verify retention/data policies for server-run features.

Workflow

Step 1: Define tool schemas

• Use explicit, validated schemas (Zod or JSON Schema) for both inputs and outputs. This reduces argument coercion, simplifies validation, and makes UIs safer to wire.

import { z } from "zod";
const getWeatherSchema = z.object({ location: z.string(), units: z.enum(["celsius","fahrenheit"]).default("fahrenheit") });

• Vercel AI SDK v6+ accepts Zod and JSON schemas as tool inputSchema/outputSchema and improves UI wiring and agent support — prefer v6 for front-end agent UIs.

Step 2: Implement tool handlers

• Keep handlers small, deterministic, and idempotent. Wrap side effects (writes, deletes) with explicit confirmations and rate-limited retries.
• Validate inputs with your schema library before executing. Return structured success/error objects so the model can adapt.

Step 3: Orchestrator loop (OpenAI Responses)

• Send messages + tools to Responses API. When the model returns a function_call, validate it, execute the requested tool, and immediately send a function_call_output with the matching call_id. The model will then continue the reasoning loop.
• For shell/computer tools, run commands in a hosted container workspace where possible and return stdout/stderr and artifact references (file paths, ids) rather than pasting huge outputs into the prompt (OpenAI "From model to agent").

Implementation checklist:

• Validate tool name and schema.
• Preserve and return call_id on function_call_output.
• Execute independent calls in parallel; serialize dependent calls.
• Summarize or store very large results and return a concise artifact reference.

Step 4: Orchestrator loop (Anthropic)

• When Claude emits one or more tool_use blocks, execute each client-callable tool and return tool_result blocks that include tool_use_id. If using programmatic tool calling, expect the model to generate code that calls tools; your orchestrator will still receive tool_use blocks to fulfill.
• Use strict: true on input schemas when you want exact conformance and less post-processing.
• Anthropic supports parallel tool execution; if you require ordered execution, use the available option to disable parallel calls (see Anthropic tool docs).

Examples and patterns

• Parallel tool execution: run independent function_call/tool_use items concurrently and return results each with their original id.
• Programmatic tool calling (Anthropic): let Claude run a short script in the code_execution environment to aggregate many low-level queries, returning a small, relevant summary to the model.
• Error recovery: apply retries with exponential backoff for transient errors; for permanent failures, return structured errors (e.g. {status:"error", code:..., message:...}) so the model can ask for clarification or fall back.

Edge cases and gotchas (updated)

• Hallucinated tool names: always verify model-specified tool names against a server-side registry before executing.
• Id pairing and ordering: OpenAI function_call must be followed by function_call_output referencing the same call_id; Anthropic tool_use/tool_result blocks must preserve tool_use_id. Many community issues arise from mismatched ids or delayed replies — preserve ids exactly and return outputs promptly (OpenAI docs & community threads; Anthropic docs).
• Argument type coercion: models may send strings for numeric fields. Use Zod/JSON schema coercion or explicit parsing and return a helpful structured error when coercion fails.
• Parallel vs serialized calls: providers support parallel tool use for throughput; disable parallel execution when ordering matters (Anthropic docs note disable_parallel_tool_use as an option).
• Long results and context bloat: summarize, persist to workspace, or return artifact ids rather than inlining large payloads.
• Streaming: tool calls and outputs may arrive in deltas during streaming. Accumulate and validate before acting.
• Infinite loops: set a max iteration limit and track recent tool calls to detect loops.

Evaluation criteria

• Tool selection accuracy: % correct tool chosen for an intent
• Argument accuracy: % of tool calls with valid, complete arguments
• Execution success rate: % of tool calls that succeed on first attempt
• Loop efficiency: average tool calls per task
• Error recovery: % of failed calls where the model adapts successfully
• Latency per tool turn: time from model response to tool result submitted

Research-backed changes (sources)

• Added Responses API computer environment and shell tool guidance (OpenAI blog "From model to agent", March 11, 2026).
• Reinforced call_id / function_call_output pairing and common community pitfalls (OpenAI docs + community threads).
• Added Anthropic programmatic tool calling details, allowed_callers, and code_execution workflow (Anthropic Tool Use docs).
• Updated front-end SDK guidance to prefer Vercel AI SDK v6 for inputSchema/outputSchema and agent tooling improvements (Vercel AI SDK docs).