DESIGNING GOOD TOOLS

EXAMPLES Example 1: Naming. A tool named doStuff takes a text field called data. Given a request to put a dentist appointment on the calendar, the model has no idea whether doStuff is the right choice, so it guesses, and sometimes guesses wrong. A tool named create_calendar_event, described as "Creates a calendar event with a title, start time, end time, and optional attendees list. Times are in International Organization for Standardization (ISO) format, for example 2026-03-05T14:00," lets the model use it correctly on the first try. Example 2: Composable design. A big manage_project tool has an action field and fifteen other optional fields. The model keeps passing the wrong combination. The team replaces it with create_task (title, due date), assign_task (task id, person), and mark_task_done (task id). Now a request like "Create a task to order supplies, give it to Maria, and mark the earlier task done" becomes three simple calls, and each call is easy to test. Example 3: A helpful error. The model calls read_file with the path /home/user/project/src/main.py. The tool replies: "Error: file_path must be relative to the project root; you passed an absolute path. Try 'src/main.py'." On its next step, the model sends src/main.py and succeeds. No person was involved, and the loop continued smoothly. Example 4: Idempotency. An order system has two designs. In design A, set_status_to_shipped sets the order status to shipped. If the network drops and the harness retries, the order is shipped both times, and no harm results. In design B, increment_ship_count adds 1 to a counter each time. A retry after a timeout makes the count 2 for a single shipment, and the monthly shipping report is wrong. The fix is to turn design B into a set operation or to add an idempotency key, so a repeated request with the same key changes nothing.