Tool Calling

• A tool = a function the model asks for by name with JSON arguments
• The model never runs it; your code does
• Definition has 3 parts: name, description, input JSON schema
• The description is the prompt: it tells the model when to use the tool

• Who executes a call? Your app, never the model
• What does the model output? A tool call: name, id, JSON arguments
• How do you know it wants a tool? tool_use / tool_calls; end_turn / stop means final

• Description: what it does, when to use it, when not, each arg's format
• Fixed choices → enum; keep params flat
• additionalProperties: false asks for no extra keys; enforced only with strict tool use

{"name":"get_weather","input_schema":{"type":"object",
"properties":{"location":{"type":"string"},
"unit":{"enum":["celsius","fahrenheit"]}},
"required":["location"],
"additionalProperties":false}}

the model's call is below

• Vague names like do_action
• Many overlapping tools
• Optional fields marked required: model invents values

• Why validate? The schema only guides the model; check values server side
• Wrong tool? Sharp descriptions, few distinct tools, narrow schemas
• In a description? What, when, when not, argument formats

• Match each result to its call by id (tool_use_id / tool_call_id)
• Results must follow the assistant message that made the calls
• Parallel calls: run them concurrently
• Return all results together, each matched by id

for _ in range(max_turns):
    resp = model(messages, tools)
    messages.append(resp.message)
    if not resp.tool_calls: break
    for c in resp.tool_calls:
        messages.append(result(c.id, run(c)))
else: raise RuntimeError('turn cap hit')

for/else: the cap fails loudly, not silently

• No turn cap: runaway loop and cost
• Dropped assistant tool-call message
• Result with a mismatched id

• Forced tool: input schema = your shape, set tool_choice
• Still validate values; handle refusal and max_tokens truncation

• Raising exceptions that crash the loop
• Returning raw stack traces
• Retrying forever
• Retrying payments or emails without safeguards
• No timeouts or permission checks on destructive tools

• MCP (Model Context Protocol): open standard linking AI apps to tools and data
• A host app runs several MCP clients
• Each client connects to one server
• Messages use JSON-RPC 2.0

• Tools: model-invoked actions
• Resources: readable data
• Prompts: reusable templates
• tools/list discovers tools
• tools/call invokes one

• Trusting third-party servers: prompt injection via tool output
• Over-broad permissions
• Too many tools bloat context
• Logging to stdout on stdio corrupts protocol; use stderr

• Round trip? Send tools, get call, run it, return result by id, get answer
• Function calling vs MCP? Same schemas; MCP standardizes discovery and calls
• Safe agent? Cap turns, validate, least privilege, timeouts, confirm destructive