Two Tools in Python

Until now the model could only read the shop's data. In this lesson it gets a second tool, start_return, which changes it: the order's status becomes returning.

A tool that changes data needs its own rule. Only an order that has shipped can be returned, and that rule lives in the tool's SQL, not in the model. The model decides when to ask; your code decides what is allowed. The tool then returns the order read back from the database, so the model sees the real status, changed or not.

With two tools, two things matter more. The description is how the model picks between them. And the model asks by name, a string, so your program has to find the function with that name. A dictionary does it. Here is the idea on a small calculator. The values have no parentheses: the dictionary holds the functions themselves, and you call the one you picked later.

def add(a, b):
    return a + b

def multiply(a, b):
    return a * b

operations = {"add": add, "multiply": multiply}
operation = operations["multiply"]
print(operation(3, 4))   # 12

The customer says I want to return order 4. The model checks the order first, sees that it has shipped, then asks for the return. Your program prints the first three lines. The check prints the rest, and it also tries start_return on order 6, which was cancelled:

Tool: lookup_order {'order_id': 4} -> {'id': 4, 'ordered': '2026-04-18', 'status': 'shipped'}
Tool: start_return {'order_id': 4} -> {'id': 4, 'ordered': '2026-04-18', 'status': 'returning'}
Answer: Done: I've started the return for order 4. Its status is now returning.
Model calls: 3
Tools sent: lookup_order, start_return
start_return has a description: yes
Order 4 in shop.db: returning
The check asks start_return for order 6, which was cancelled: {'id': 6, 'ordered': '2026-05-21', 'status': 'cancelled'}
Order 6 in shop.db: cancelled

Your task: write start_return with its rule, describe the tool for the model, map both tools' names to their functions in a dictionary named functions, make run_tools pick the function by block.name, and add the new tool to tools.

Assignment
Follow the Coding Tutorial to build the start_return tool and run each requested tool by its name.

Hint
In the dictionary, write lookup_order, not lookup_order(): with parentheses Python would call the function right there. And don't forget db.commit(), or the change is not saved.