Tool use & structured output

Tools on Bedrock essential

Here's the wall every beginner hits. You ask Claude "is the checkout-api pod healthy?" and it cheerfully replies — with a paragraph it invented, because a language model has no cluster to look at. It can only produce text from its training, so it guesses, and the guess sounds confident and is wrong. The model isn't broken; it's doing exactly what it was built to do. What's missing is a way for it to stop talking and ask you to go check. That mechanism is a tool.

Think of the model as a brilliant analyst locked in a room with no phone. It can reason about anything, but it cannot see live data or take an action in the world. A tool is the telephone you hand it — you don't do the work for the analyst, you give it a labelled phone it can pick up. When the analyst needs the pod's status, it doesn't hallucinate; it says "call get_pod_status with name=checkout-api" and waits. You place the call (run real code), and pass the answer back through the same phone. The model stays in charge of deciding; your code stays in charge of doing.

Now the precise version. On Bedrock's Converse API, you describe each tool with three things: a name, a plain-English description, and an inputSchema (a JSON Schema saying what arguments it takes). You pass this list in a field called toolConfig. The model reads your descriptions, and if a request looks like it needs one, it emits a structured request to call that tool instead of finishing its turn — you'll see the exact loop in the next section. This is the identical mental model as function-calling in the Anthropic SDK; only the field names differ (toolConfig/toolSpec on Bedrock's Converse rather than the SDK's tools array).

The mistake that costs people hours: treating the description as a throwaway label. It is not documentation for you — it is a prompt the model reads to decide whether to call the tool at all. A vague description like "pod tool" makes the model call it at the wrong times or skip it entirely; a precise one ("Get the status of a Kubernetes pod. Use when asked about a pod's health.") makes tool selection reliable. Write descriptions as carefully as you write prompts, because that is exactly what they are.

tools.pyimport boto3

brt = boto3.client("bedrock-runtime", region_name="us-east-1")
MODEL = "anthropic.claude-3-5-sonnet-20241022-v2:0"

TOOLS = {"tools": [{
    "toolSpec": {
        "name": "get_pod_status",
        "description": "Get the status of a Kubernetes pod. Use when asked about a pod's health.",
        "inputSchema": {"json": {
            "type": "object",
            "properties": {"name": {"type": "string", "description": "pod name"}},
            "required": ["name"],
        }},
    }
}]}

def get_pod_status(name):                       # the real implementation
    return {"name": name, "phase": "CrashLoopBackOff", "restarts": 7}

The tool loop essential

When the model wants a tool, the response stopReason is tool_use and the content holds a toolUse block. You run the tool, append a toolResult, and call again — exactly the agentic loop from Ch 4.

The single biggest confusion here trips up almost everyone the first time: the model never runs your tool. Read that again. You define a Python function called get_pod_status, you hand its schema to Bedrock — and Bedrock never touches your function. It has no access to your machine. All it can do is send back a message that means "I would like you to run get_pod_status with these arguments, and tell me the result." You run the function. The model just requests and waits. Miss this and you'll stare at the response wondering why nothing happened; grasp it and the whole protocol clicks.

The clearest analogy is a waiter taking your order. You (the model) tell the waiter "I'll have the salmon." The waiter doesn't cook — the kitchen (your code) does. The waiter carries your order to the kitchen, waits, then brings back the plate. The conversation only continues once the food arrives. A tool call is that round trip: the model orders (a toolUse block), your code cooks (runs the real function), and the dish comes back (a toolResult block) so the model can finally "eat" — that is, write its answer using real data.

Concretely, that round trip is two converse calls, not one, and this is why:

• First call — you send the user's question plus toolConfig. The model reads it, decides it needs live data, and stops early with stopReason == "tool_use". Its message contains a toolUse block naming the tool, its input, and a unique toolUseId.
• You, in between — append the model's own message to the transcript (so the history stays intact), run the named tool with that input, and wrap the return value in a toolResult block tagged with the same toolUseId. That id is the thread that stitches the answer back to the exact request; it goes back as a new user turn.
• Second call — you send the grown transcript back. Now the model has the real status and writes an ordinary sentence for the human.

Two mistakes to avoid. First, forgetting to append the model's tool-request message before you append the result — the transcript becomes incoherent and the second call errors. Second, mismatching the toolUseId: it must be copied exactly, because with several tools in flight it is the only thing telling the model which result answers which request.

tool_loop.pyimport boto3
from tools import TOOLS, get_pod_status

brt = boto3.client("bedrock-runtime", region_name="us-east-1")
MODEL = "anthropic.claude-3-5-sonnet-20241022-v2:0"

messages = [{"role": "user", "content": [{"text": "Is the checkout-api pod healthy?"}]}]

resp = brt.converse(modelId=MODEL, messages=messages, toolConfig=TOOLS)

if resp["stopReason"] == "tool_use":
    messages.append(resp["output"]["message"])                  # remember the tool request
    for block in resp["output"]["message"]["content"]:
        if "toolUse" in block:
            tu = block["toolUse"]
            result = get_pod_status(**tu["input"])              # run it
            messages.append({"role": "user", "content": [{
                "toolResult": {
                    "toolUseId": tu["toolUseId"],
                    "content": [{"json": result}],
                }
            }]})
    final = brt.converse(modelId=MODEL, messages=messages, toolConfig=TOOLS)
    print(final["output"]["message"]["content"][0]["text"])

The checkout-api pod is not healthy: it is in CrashLoopBackOff with 7 restarts, which means the container keeps failing to start.

Structured output via a tool intermediate

You have almost certainly written this brittle code, or inherited it. You ask the model to "classify this ticket and return JSON with severity, category, and needs_human," and it obliges — mostly. Then one day it wraps the JSON in a chatty preamble ("Sure! Here's the classification:"), or fences it in ```json, or invents a field you didn't ask for, or spells severity "Critical" instead of "critical." Your json.loads() throws, or worse, silently succeeds with the wrong shape, and a downstream service falls over at 2am. The root problem: you asked for JSON with words, and words are a suggestion the model is free to reinterpret.

Here's the trick that makes the whole class of bugs vanish, and it's a lovely bit of lateral thinking: you already have a mechanism that guarantees a rigid, validated shape — the tool schema. A tool's inputSchema is a contract the model must satisfy to call the tool. So instead of using tools only to do things, you use one to capture your answer. Define a tool named something like record_triage whose input schema is exactly the JSON shape you want out. You never intend to "run" it — the arguments the model fills in to call it are your output. It's like handing someone a form with labelled boxes instead of a blank page: they can't ramble, they can only fill the boxes.

The last piece is making it non-optional. Left to its own judgement the model might still answer in prose, so you set toolChoice to force that specific tool — telling Bedrock "you must call record_triage, no free text allowed." Now the model has exactly one way to respond: populate the schema. You read the answer from toolUse.input, which is a plain dict guaranteed to match your properties and required fields — no regex, no fence-stripping, no defensive parsing.

The real power is in constrained fields. Note the severity uses an "enum" of ["low","medium","high","critical"]. That is not decoration — it means the model cannot return "urgent" or "Critical" or "sev-1"; the value it gives you is provably one of your four allowed strings, safe to feed straight into a switch or a database column. This is the difference between "usually valid" and "valid by construction," and it is why forced-tool structured output is the standard way to get machine-readable data out of a model on Bedrock.

structured.pyimport boto3

brt = boto3.client("bedrock-runtime", region_name="us-east-1")
MODEL = "anthropic.claude-3-5-sonnet-20241022-v2:0"

CLASSIFY = {"tools": [{"toolSpec": {
    "name": "record_triage",
    "description": "Record the triage classification of a support ticket.",
    "inputSchema": {"json": {
        "type": "object",
        "properties": {
            "severity": {"type": "string", "enum": ["low", "medium", "high", "critical"]},
            "category": {"type": "string"},
            "needs_human": {"type": "boolean"},
        },
        "required": ["severity", "category", "needs_human"],
    }},
}}]}

resp = brt.converse(
    modelId=MODEL,
    messages=[{"role": "user", "content": [{"text": "Ticket: 'prod DB is down, customers affected'"}]}],
    toolConfig={**CLASSIFY, "toolChoice": {"tool": {"name": "record_triage"}}},  # force the tool
)
for block in resp["output"]["message"]["content"]:
    if "toolUse" in block:
        print(block["toolUse"]["input"])   # a dict matching the schema

{'severity': 'critical', 'category': 'database-outage', 'needs_human': True}

TOOLS = {"tools": [{
    "toolSpec": {
        "name": "get_weather",
        "description": "Get current weather for a city.",
        "inputSchema": {"json": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        }},
    }
}]}
assert TOOLS["tools"][0]["toolSpec"]["name"] == "get_weather"
print("tool spec ok")

import boto3

brt = boto3.client("bedrock-runtime", region_name="us-east-1")
TOOLS = {"tools": [{"toolSpec": {"name": "get_weather",
    "description": "Weather for a city.",
    "inputSchema": {"json": {"type":"object",
        "properties":{"city":{"type":"string"}}, "required":["city"]}}}}]}

r = brt.converse(
    modelId="anthropic.claude-3-5-sonnet-20241022-v2:0",
    messages=[{"role":"user","content":[{"text":"Weather in Paris?"}]}],
    toolConfig=TOOLS,
)
if r["stopReason"] == "tool_use":
    for b in r["output"]["message"]["content"]:
        if "toolUse" in b:
            print(b["toolUse"]["name"], b["toolUse"]["input"])

import boto3

brt = boto3.client("bedrock-runtime", region_name="us-east-1")
TOOLS = {"tools": [{"toolSpec": {"name":"get_weather","description":"w",
    "inputSchema":{"json":{"type":"object",
      "properties":{"city":{"type":"string"}},"required":["city"]}}}}]}

def run_tool(name, inp):
    return {"tempC": 18} if name == "get_weather" else {}

msgs = [{"role":"user","content":[{"text":"Weather in Paris?"}]}]
r = brt.converse(modelId="anthropic.claude-3-5-sonnet-20241022-v2:0",
                 messages=msgs, toolConfig=TOOLS)
if r["stopReason"] == "tool_use":
    msgs.append(r["output"]["message"])              # model's turn
    for b in r["output"]["message"]["content"]:
        if "toolUse" in b:
            tu = b["toolUse"]
            result = run_tool(tu["name"], tu["input"])
            msgs.append({"role":"user","content":[{"toolResult":{
                "toolUseId": tu["toolUseId"],
                "content": [{"json": result}]}}]})
    final = brt.converse(modelId="anthropic.claude-3-5-sonnet-20241022-v2:0",
                         messages=msgs, toolConfig=TOOLS)
    print(final["output"]["message"]["content"][0]["text"])

import boto3

brt = boto3.client("bedrock-runtime", region_name="us-east-1")
TOOLS = {"tools": [{"toolSpec": {"name":"record_ticket",
  "description":"Structured ticket.",
  "inputSchema":{"json":{"type":"object","properties":{
     "priority":{"type":"string","enum":["low","high"]},
     "summary":{"type":"string"}},"required":["priority","summary"]}}}}],
  "toolChoice": {"tool": {"name": "record_ticket"}}}

r = brt.converse(modelId="anthropic.claude-3-5-sonnet-20241022-v2:0",
    messages=[{"role":"user","content":[{"text":"Server down, urgent!"}]}],
    toolConfig=TOOLS)
for b in r["output"]["message"]["content"]:
    if "toolUse" in b:
        print(b["toolUse"]["input"])   # {'priority':'high','summary':...}

REGISTRY = {
    "get_weather": lambda a: {"tempC": 18},
    "get_time":    lambda a: {"iso": "2026-01-01T00:00:00Z"},
}

def dispatch(name, inp):
    fn = REGISTRY.get(name)
    if not fn:
        return {"error": f"unknown tool {name}"}
    return fn(inp)

# offline check of the dispatch table:
print(dispatch("get_weather", {"city":"Paris"}))   # {'tempC': 18}
print(dispatch("nope", {}))                          # {'error': 'unknown tool nope'}
# In production the converse loop calls dispatch() for each toolUse block,
# appends a toolResult keyed by toolUseId, and re-calls converse until done.

def order_service(order_id):                 # stub for a real API/db
    db = {"A100": {"status": "shipped", "eta": "2026-01-05"}}
    return db.get(order_id, {"status": "not_found"})

TOOLS = {"tools": [{"toolSpec": {"name":"lookup_order",
  "description":"Look up an order by id.",
  "inputSchema":{"json":{"type":"object",
     "properties":{"order_id":{"type":"string"}},
     "required":["order_id"]}}}}]}

# offline: prove the tool returns feedable JSON
print(order_service("A100"))    # {'status':'shipped','eta':'2026-01-05'}
# In the loop: on stopReason=='tool_use', call order_service(input['order_id']),
# append {'toolResult':{'toolUseId':..,'content':[{'json': result}]}}, re-converse.

Knowledge check check yourself