Tool Use at the API Level: The Primitive

Underneath every agent framework is the same primitive — the model returns a structured tool call, you execute it, you feed the result back. Master this loop and every framework looks familiar.

50 min · Reviewed 2026

The primitive under every agent

All three major API providers — Anthropic, OpenAI, Google — implement tool use the same way. You send a request that includes tool definitions. The model either replies with text OR returns a 'tool_use' block with a name and arguments. Your code runs the tool and sends the result back in a 'tool_result' block. Repeat until the model returns a final text answer.

The canonical Claude example

import anthropic

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "Get current weather for a city.",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "City name"},
                "unit": {"type": "string", "enum": ["C", "F"]}
            },
            "required": ["city"]
        }
    }
]

messages = [{"role": "user", "content": "What's the weather in Tokyo?"}]

while True:
    resp = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        tools=tools,
        messages=messages,
    )
    if resp.stop_reason == "end_turn":
        print(resp.content[0].text)
        break
    if resp.stop_reason == "tool_use":
        tool_use = next(b for b in resp.content if b.type == "tool_use")
        result = run_tool(tool_use.name, tool_use.input)  # your code
        messages.append({"role": "assistant", "content": resp.content})
        messages.append({
            "role": "user",
            "content": [{
                "type": "tool_result",
                "tool_use_id": tool_use.id,
                "content": str(result)
            }]
        })The agent loop, from scratch, in ~25 lines. Everything else is sugar on top.

The three provider shapes

Aspect	Anthropic	OpenAI	Google
Field name	tools + tool_use + tool_result	tools + function_call + tool response	tools + functionCall + functionResponse
Schema style	JSON Schema under input_schema.	JSON Schema under parameters.	JSON Schema under parameters.
Parallel calls	Yes (multiple tool_use blocks).	Yes (tool_calls array).	Yes (functionCalls array).
Forced tool	tool_choice: {type: 'tool', name: X}.	tool_choice: {type: 'function', function: {name: X}}.	function_calling_config: {mode: 'ANY'}.
Streaming tool calls	Yes, with delta events.	Yes.	Yes.

Writing good tool schemas

Description is a prompt — models decide based on it. Be specific about when to use the tool, when NOT to.
Use enums to constrain string params — eliminates spelling mistakes.
Require only fields the tool truly needs. Optional fields are fine.
Name things like you'd name a function: send_email, query_db, list_files.
Return errors as structured JSON, not paragraphs. 'error_code' + 'message' + 'retriable: bool'.

Parallel tool calls

All three providers emit multiple tool calls per turn when independent. If the model needs to look up weather in Tokyo, London, and Paris, it returns three tool_use blocks at once. You execute them in parallel and return all three tool_result blocks in the next user message. This is 3x faster than sequential.

# Parallel execution pattern
import asyncio

async def handle_tools(tool_uses):
    results = await asyncio.gather(*[
        run_tool_async(t.name, t.input) for t in tool_uses
    ])
    return [
        {"type": "tool_result", "tool_use_id": t.id, "content": str(r)}
        for t, r in zip(tool_uses, results)
    ]Run parallel tool calls in parallel. Don't serialize by accident.

Extended / adaptive thinking + tools

Claude's extended thinking (Opus 4.7, Opus 4.6, Sonnet 4.6) enables interleaved thinking between tool calls. The model can reason about a tool result before deciding the next action. Anthropic recommends adaptive thinking (default 'high' effort) for any agentic workload. Pass thinking: {type: 'enabled', budget_tokens: 8000} to turn it on.

End-of-lesson check

15 questions · take it digitally for instant feedback at tendril.neural-forge.io/learn/quiz/end-agentic-tool-use-api-creators

What is the core idea behind "Tool Use at the API Level: The Primitive"?
1. Underneath every agent framework is the same primitive — the model returns a structured tool call, you execute it, you feed the result back. Master this loop and every framework looks familiar.
2. college apps
3. resumability
4. tenant ID
Which term best describes a foundational idea in "Tool Use at the API Level: The Primitive"?
1. function calling
2. tool use
3. input_schema
4. tool_use_id
A learner studying Tool Use at the API Level: The Primitive would need to understand which concept?
1. tool use
2. input_schema
3. function calling
4. tool_use_id
Which of these is directly relevant to Tool Use at the API Level: The Primitive?
1. tool use
2. function calling
3. tool_use_id
4. input_schema
Which of the following is a key point about Tool Use at the API Level: The Primitive?
1. Description is a prompt — models decide based on it.
2. Use enums to constrain string params — eliminates spelling mistakes.
3. Require only fields the tool truly needs. Optional fields are fine.
4. Name things like you'd name a function: send_email, query_db, list_files.
Which of these does NOT belong in a discussion of Tool Use at the API Level: The Primitive?
1. Require only fields the tool truly needs. Optional fields are fine.
2. college apps
3. Description is a prompt — models decide based on it.
4. Use enums to constrain string params — eliminates spelling mistakes.
What is the key insight about "Tool-use hallucinations happen" in the context of Tool Use at the API Level: The Primitive?
1. college apps
2. resumability
3. Models occasionally invent tool names that don't exist, or call tools with wrong schema.
4. tenant ID
What is the key insight about "Everything is this, over and over" in the context of Tool Use at the API Level: The Primitive?
1. college apps
2. resumability
3. tenant ID
4. LangGraph, CrewAI, AutoGen, Claude Code — all wrap this same primitive loop.
What is the key warning about "Scope your agents tightly" in the context of Tool Use at the API Level: The Primitive?
1. Always define: goal, tools, permissions, and stop condition before executing.
2. college apps
3. resumability
4. tenant ID
Which statement accurately describes an aspect of Tool Use at the API Level: The Primitive?
1. college apps
2. All three major API providers — Anthropic, OpenAI, Google — implement tool use the same way.
3. resumability
4. tenant ID
What does working with Tool Use at the API Level: The Primitive typically involve?
1. college apps
2. resumability
3. All three providers emit multiple tool calls per turn when independent. If the model needs to look up weather in Tokyo, London, and Paris, i…
4. tenant ID
Which of the following is true about Tool Use at the API Level: The Primitive?
1. college apps
2. resumability
3. tenant ID
4. Claude's extended thinking (Opus 4.7, Opus 4.6, Sonnet 4.6) enables interleaved thinking between tool calls.
Which best describes the scope of "Tool Use at the API Level: The Primitive"?
1. It focuses on Underneath every agent framework is the same primitive — the model returns a structured tool call, y
2. It is unrelated to agentic workflows
3. It applies only to the opposite beginner tier
4. It was deprecated in 2024 and no longer relevant
Which section heading best belongs in a lesson about Tool Use at the API Level: The Primitive?
1. college apps
2. The canonical Claude example
3. resumability
4. tenant ID
Which section heading best belongs in a lesson about Tool Use at the API Level: The Primitive?
1. college apps
2. resumability
3. The three provider shapes
4. tenant ID

← Back to interactive lesson

Tendril · Creators · Agentic AI

Tool Use at the API Level: The Primitive

Underneath every agent framework is the same primitive — the model returns a structured tool call, you execute it, you feed the result back. Master this loop and every framework looks familiar.

50 min · Reviewed 2026

The primitive under every agent

The canonical Claude example

import anthropic

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "Get current weather for a city.",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "City name"},
                "unit": {"type": "string", "enum": ["C", "F"]}
            },
            "required": ["city"]
        }
    }
]

messages = [{"role": "user", "content": "What's the weather in Tokyo?"}]

while True:
    resp = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        tools=tools,
        messages=messages,
    )
    if resp.stop_reason == "end_turn":
        print(resp.content[0].text)
        break
    if resp.stop_reason == "tool_use":
        tool_use = next(b for b in resp.content if b.type == "tool_use")
        result = run_tool(tool_use.name, tool_use.input)  # your code
        messages.append({"role": "assistant", "content": resp.content})
        messages.append({
            "role": "user",
            "content": [{
                "type": "tool_result",
                "tool_use_id": tool_use.id,
                "content": str(result)
            }]
        })The agent loop, from scratch, in ~25 lines. Everything else is sugar on top.

The three provider shapes

Aspect	Anthropic	OpenAI	Google
Field name	tools + tool_use + tool_result	tools + function_call + tool response	tools + functionCall + functionResponse
Schema style	JSON Schema under input_schema.	JSON Schema under parameters.	JSON Schema under parameters.
Parallel calls	Yes (multiple tool_use blocks).	Yes (tool_calls array).	Yes (functionCalls array).
Forced tool	tool_choice: {type: 'tool', name: X}.	tool_choice: {type: 'function', function: {name: X}}.	function_calling_config: {mode: 'ANY'}.
Streaming tool calls	Yes, with delta events.	Yes.	Yes.

Writing good tool schemas

Description is a prompt — models decide based on it. Be specific about when to use the tool, when NOT to.
Use enums to constrain string params — eliminates spelling mistakes.
Require only fields the tool truly needs. Optional fields are fine.
Name things like you'd name a function: send_email, query_db, list_files.
Return errors as structured JSON, not paragraphs. 'error_code' + 'message' + 'retriable: bool'.

Parallel tool calls

# Parallel execution pattern
import asyncio

async def handle_tools(tool_uses):
    results = await asyncio.gather(*[
        run_tool_async(t.name, t.input) for t in tool_uses
    ])
    return [
        {"type": "tool_result", "tool_use_id": t.id, "content": str(r)}
        for t, r in zip(tool_uses, results)
    ]Run parallel tool calls in parallel. Don't serialize by accident.

Extended / adaptive thinking + tools

End-of-lesson check

15 questions · take it digitally for instant feedback at tendril.neural-forge.io/learn/quiz/end-agentic-tool-use-api-creators

What is the core idea behind "Tool Use at the API Level: The Primitive"?
1. Underneath every agent framework is the same primitive — the model returns a structured tool call, you execute it, you feed the result back. Master this loop and every framework looks familiar.
2. college apps
3. resumability
4. tenant ID
Which term best describes a foundational idea in "Tool Use at the API Level: The Primitive"?
1. function calling
2. tool use
3. input_schema
4. tool_use_id
A learner studying Tool Use at the API Level: The Primitive would need to understand which concept?
1. tool use
2. input_schema
3. function calling
4. tool_use_id
Which of these is directly relevant to Tool Use at the API Level: The Primitive?
1. tool use
2. function calling
3. tool_use_id
4. input_schema
Which of the following is a key point about Tool Use at the API Level: The Primitive?
1. Description is a prompt — models decide based on it.
2. Use enums to constrain string params — eliminates spelling mistakes.
3. Require only fields the tool truly needs. Optional fields are fine.
4. Name things like you'd name a function: send_email, query_db, list_files.
Which of these does NOT belong in a discussion of Tool Use at the API Level: The Primitive?
1. Require only fields the tool truly needs. Optional fields are fine.
2. college apps
3. Description is a prompt — models decide based on it.
4. Use enums to constrain string params — eliminates spelling mistakes.
What is the key insight about "Tool-use hallucinations happen" in the context of Tool Use at the API Level: The Primitive?
1. college apps
2. resumability
3. Models occasionally invent tool names that don't exist, or call tools with wrong schema.
4. tenant ID
What is the key insight about "Everything is this, over and over" in the context of Tool Use at the API Level: The Primitive?
1. college apps
2. resumability
3. tenant ID
4. LangGraph, CrewAI, AutoGen, Claude Code — all wrap this same primitive loop.
What is the key warning about "Scope your agents tightly" in the context of Tool Use at the API Level: The Primitive?
1. Always define: goal, tools, permissions, and stop condition before executing.
2. college apps
3. resumability
4. tenant ID
Which statement accurately describes an aspect of Tool Use at the API Level: The Primitive?
1. college apps
2. All three major API providers — Anthropic, OpenAI, Google — implement tool use the same way.
3. resumability
4. tenant ID
What does working with Tool Use at the API Level: The Primitive typically involve?
1. college apps
2. resumability
3. All three providers emit multiple tool calls per turn when independent. If the model needs to look up weather in Tokyo, London, and Paris, i…
4. tenant ID
Which of the following is true about Tool Use at the API Level: The Primitive?
1. college apps
2. resumability
3. tenant ID
4. Claude's extended thinking (Opus 4.7, Opus 4.6, Sonnet 4.6) enables interleaved thinking between tool calls.
Which best describes the scope of "Tool Use at the API Level: The Primitive"?
1. It focuses on Underneath every agent framework is the same primitive — the model returns a structured tool call, y
2. It is unrelated to agentic workflows
3. It applies only to the opposite beginner tier
4. It was deprecated in 2024 and no longer relevant
Which section heading best belongs in a lesson about Tool Use at the API Level: The Primitive?
1. college apps
2. The canonical Claude example
3. resumability
4. tenant ID
Which section heading best belongs in a lesson about Tool Use at the API Level: The Primitive?
1. college apps
2. resumability
3. The three provider shapes
4. tenant ID

← Back to interactive lesson