AI Architecture Pattern 05: Tool Calling

[!NOTE] This is Video 1 of 2 — the full design walkthrough and real AWS build. Video 2 (hands-on live demo) is coming soon.

Mike opens the assistant that’s answered every payment question so far and asks something new: “What’s my current balance?”

Every pattern before this one — Pattern 01, Pattern 02, Pattern 03, Pattern 04 — solved a real problem in the same assistant, and each fix quietly assumed one thing: that the app already knows, before the model is even called, exactly what data the model will need. That assumption breaks on a question like this one. A balance has to be current, and the app can’t know in advance which of a dozen possible questions Mike is about to ask.

This is the pattern that lets the model ask for its own data, live, instead of reasoning from whatever the app guessed it might need.

The picture above is the whole idea at 30,000 feet: the model doesn’t answer immediately — it tells the app what it needs, the app fetches it, and only then does the model compose the final answer.

[!NOTE] This post is part of a continuing 16-pattern series: a payment-support assistant at a fictional bank, starting simple and accumulating exactly the complexity a real one would, in the order a real one would need it. Read the series overview or clone the GitHub repo to follow along.

Where the first four patterns left off

Same assistant, same story, one new architectural gap closed per pattern.

Pattern 01 — Grounded RAG. Mike asks why his payment is pending. The assistant gives a fluent, completely fabricated answer — it reasoned from training data, not his real transaction. The fix: retrieve the real record first, generate the answer second. Left open: retrieval finding the right document doesn’t guarantee the model draws the right conclusion from it.

Pattern 02 — Prompt and Context Contract. A second team plugs their own data into Pattern 01’s assistant. It crashes with a raw KeyError, two layers below where the actual problem was. The fix: validate the shape of every input before rendering a prompt with it. Left open: a contract only checks shape — not whether a correctly-typed value is actually the right value.

Pattern 03 — Structured Output and Validation. A dispute’s status comes back as "still being looked at" — present, correctly typed, so it passes Pattern 02’s contract clean. But the routing queue only recognizes four exact enum values, and this isn’t one of them — the dispute sits unrouted, no error, no alert. The fix: constrain the model at generation time so this exact failure can’t be produced. Left open: a schema-valid value still isn’t automatically the correct one.

Pattern 04 — Evaluator Optimizer. Mike asks when his refund arrives. The model answers confidently: “by Friday.” Policy says 5–10 business days — Friday is impossible. The fix: a second, independent model call grades the first against the same policy context, and a failing grade triggers a rewrite. Left open — and this is the sentence the rest of this post exists to answer — the judge only ever grades the draft against whatever context the app already fetched. It has no way to know if that pre-fetched data was itself stale by the time the question was actually asked.

Two things worth clearing up before going further

“Doesn’t Pattern 01 already use a real database? What’s actually new here?”

Yes — Pattern 01’s lookup already hits a real datastore in production. Swap the local file for a live DynamoDB call and nothing about Pattern 01’s architecture changes. The datastore itself was never the variable across this series.

What actually changes at this pattern is who decides to go fetch data, and when. In Patterns 01 through 04, that decision is made once, by the developer, before the model ever reads the question. From this pattern on, the model itself makes that decision, live, in the middle of composing its answer.

“So now that the model can call tools, do we still need the contract and schema checks from Patterns 02 and 03?”

More than ever, not less. Handing a model the ability to trigger a real function call is more power than handing it a paragraph of pre-fetched context — and more power calls for more boundary discipline, not less. Every earlier pattern’s job still runs here, just relocated:

• Pattern 02’s contract now enforces the tool’s input, not the prompt’s. The server unconditionally overwrites whatever account_id the model supplies with the authenticated session’s real value, on every single tool call — skipping this is a textbook confused-deputy vulnerability.
• Pattern 03’s structured output now constrains what the model is allowed to request, via a JSON Schema on every tool definition.
• Pattern 04’s evaluator still applies, unchanged, to the model’s final answer. Fresh, correctly-fetched data doesn’t guarantee the sentence built from it is accurate. Live data fixes staleness. It does not fix reasoning errors.

The whole series so far, on one page

What tool calling actually looks like

One model call becomes two.

Call 1 — the question, plus a menu of tools the model is allowed to use:

response = client.converse(
    modelId="amazon.nova-micro-v1:0",
    messages=[{"role": "user", "content": [{"text": "What is my balance?"}]}],
    toolConfig={
        "tools": [{
            "toolSpec": {
                "name": "get_balance",
                "description": "Retrieve the current account balance for a given account ID.",
                "inputSchema": {"json": {
                    "type": "object",
                    "properties": {"account_id": {"type": "string"}},
                    "required": ["account_id"],
                }},
            }
        }],
        "toolChoice": {"auto": {}},
    },
)

The model doesn’t answer yet. It returns stopReason="tool_use" and names the tool it wants and the arguments it wants to call it with. It has signaled intent — it cannot execute anything itself.

The app executes the tool — and this is where the contract enforcement lives:

tool_input = dict(tool_use["input"])
tool_input["account_id"] = account_id  # authenticated session value — never trust the model's own
result = get_balance(tool_input["account_id"])

Call 2 — send the real result back, the model composes the final answer:

response = client.converse(
    modelId="amazon.nova-micro-v1:0",
    messages=[user_msg, assistant_tool_use_msg, tool_result_msg],
    toolConfig=TOOL_CONFIG,
)
# stopReason == "end_turn" — this is the real, live answer

The model can request more than one tool in a single turn — a compound question like “my balance and my recent transactions” returns two tool-use blocks, executed together, answered together. If the model needs a second round after seeing the first result, the loop continues, bounded by a fixed round limit so it can never run forever.

That’s the full loop end to end, including the two guardrails that don’t show up in the two-call summary above: the app never trusts the model’s own account_id, and a bounded round counter stops a chain of tool calls from running forever.

Which variation do you actually need?

Tool calling isn’t one fixed shape — the demo above is the baseline, but real questions call for small, deliberate variations on it.

Every row except the last is still this same pattern — one parameter or one code path changed, same explicit, auditable two-call loop underneath. The moment a requirement pushes past that last row, the honest answer is “that’s a different architecture,” not “we can bolt it on.”

This is the path this series actually built and demoes on camera — a single Lambda owns the two-call loop end to end, so every tool call, every enforced account_id, and every round of the loop is visible in one place, in your own logs.

Bedrock Agents is the managed alternative — same underlying idea, but the loop itself runs inside the service instead of your own code.

toolConfig vs. Bedrock Agents, the actual dissection: with toolConfig, every call is visible, logged, and auditable in app code — the loop mechanics are the lesson here, and that matters for a compliance-facing payment flow. Bedrock Agents is the right tool when you want autonomous multi-step chaining with session memory and don’t need per-call audit visibility — genuinely valid, just not the fit for this pattern’s problem.

Already on a framework? LangGraph’s ToolNode and Strands Agents both reach the same underlying toolConfig/toolUse mechanics — LangGraph via an AWS-published sample, Strands via its @tool decorator, which generates the same toolSpec this post hand-builds. Neither replaces the explicit, auditable loop this pattern teaches; they wrap it for you instead of hand-writing it.

When this pattern is the right call, and when it isn’t

Reach for tool calling when the shape of the question genuinely can’t be predicted in advance, or the data has to be live at the exact moment the model answers — a balance, a real-time status, anything the app can’t safely pre-fetch without either over-fetching “just in case” or under-fetching and answering from something already stale.

Don’t reach for it when the data barely changes and the question shape is predictable — Pattern 01’s “why is my payment pending” is always the same lookup, and a single model call handles it more simply and more cheaply than two. Tool calling adds a full extra round trip; that cost only earns its keep when the flexibility is actually needed.

Where this goes next

Tool calling is the foundation the rest of the agentic patterns in this series build on: a model that can pause mid-answer, request something it needs, and continue. Pattern 06 (Memory) and Pattern 07 (Workflow Orchestration) both extend this same loop rather than reinventing it.

[!TIP] Star the GitHub repo and follow along with the series.

response = client.converse(
    modelId="amazon.nova-micro-v1:0",
    messages=[{"role": "user", "content": [{"text": question}]}],
    toolConfig={"tools": [...], "toolChoice": {"auto": {}}},
)

messages.append(assistant_message)  # Call 1's assistant message
messages.append({
    "role": "user",
    "content": [{"toolResult": {"toolUseId": "...", "content": [{"json": result}], "status": "success"}}]
})
response2 = client.converse(modelId=..., messages=messages, toolConfig=...)

tool_use_blocks = []
for block in assistant_message.get("content", []):
    if "toolUse" in block:
        tool_use_blocks.append(block["toolUse"])

{
    "toolResult": {
        "toolUseId": "tooluse_abc123",   # must match the Call 1 value exactly
        "content": [{"json": {"balance": 4823.50, ...}}],
        "status": "success"
    }
}

tool_result_content = []
for tool_use in tool_use_blocks:  # iterate all toolUse blocks
    result = run_tool(tool_use["name"], tool_use["input"])
    tool_result_content.append({
        "toolResult": {
            "toolUseId": tool_use["toolUseId"],   # matched by ID
            "content": [{"json": result}],
            "status": "success"
        }
    })

# One Call 2 with ALL results
messages.append({"role": "user", "content": tool_result_content})

while round_num < MAX_TOOL_ROUNDS:
    response = client.converse(...)
    if response["stopReason"] == "end_turn":
        return extract_answer(response)
    if response["stopReason"] == "tool_use":
        # execute tools, append toolResult, loop again
        round_num += 1
return safe_fallback_answer  # budget exhausted

try:
    result = run_tool(name, tool_input)
    status = "success"
except Exception as exc:
    result = {"error": str(exc)}
    status = "error"

{"toolResult": {"toolUseId": tool_use_id, "content": [{"json": result}], "status": status}}

Have questions or feedback? Drop a comment below or connect on LinkedIn.