Run AI tool requests: recover from format errors and lost replies

1. 1

   A proposed action is followed by program execution

   A reading group wants to check two copies of a book and prepare a draft for staff review. A fluent “done” message is not execution evidence. This lesson follows a proposed tool request, local validation, execution and the result returned to AI.

   The workflow to understand is: Distinguish AI proposals from program execution → define tool names and inputs → understand request validation → explain errors for revision → understand recovery after lost replies without duplicate results. First learn why each input and constraint matters, then study the requests, finished examples and explanations. This is a reading lesson about external AI tools; no account or runtime is required.

   A tool is a named program operation. lookup_stock reads fictional availability; create_draft prepares a review draft. AI proposes the tool and arguments, while application code decides whether and how to execute them. A JSON proposal alone cannot establish task completion.

   We recorded real Claude Sonnet 5.5 conversations, then replayed their textual proposals through an editor-written Python runner. These are not captured API tool_use blocks. The lesson explicitly separates model text, local tool execution and returned results before introducing a production API integration.

   All stock, timestamps, IDs and drafts are fictional. The runner has no connection to a library, reservation system, email or external database, and its in-memory drafts disappear when it exits. You can inspect format failures and duplicate prevention without an API account or payment.

   The target is one review draft associated with request R101. Recovery should preserve that identity rather than creating another draft every time a reply is lost. Follow the proposal, observed result and draft count tables if you prefer not to run Python.

2. 2

   Give AI a small, explicit tool contract

   The initial prompt contains the user goal and two tool contracts: names, required arguments, result shapes and retry behaviour. lookup_stock requires book_id; create_draft requires request_id, book_id, quantity and note. An explicit allowlist prevents accepting an invented operation such as send_email.

   

   Only books B17 and B22 exist, and quantity must be an integer from one to three. R101 identifies this particular task across retries. Reusing the ID with changed arguments is a conflict, not permission to overwrite an earlier draft.

   Stock is initially unknown, so ask AI for only the next operation. After lookup executes, provide its result before requesting a draft. This turns a vague multi-action completion into observable steps with evidence between them.

   The expected output is one JSON object containing name and arguments. JSON is a structured interchange format with strict syntax. Explanations or Markdown fences can prevent a JSON parser from reading an otherwise sensible proposal, so prompt instructions and local validation are separate requirements.

   Use an ordinary new chat for this exercise, explicitly stating that no external tools should run. Later production integration must follow the provider's actual tool definitions and result-message format. This text replay teaches the control flow without claiming to implement that wire protocol.

   This is a fictional teaching case. Propose a tool request as text; do not actually execute anything. A book club needs to check two copies of B17, then create a draft for staff review. Do not confirm a reservation or send email.
   Available tools:
   lookup_stock({book_id:string}) returns {book_id,available,checked_at}. Read only. Allowed book IDs: B17,B22.
   create_draft({request_id:string,book_id:string,quantity:integer,note:string}) returns {draft_id,status:"draft"}. In-memory practice only. Quantity 1–3. The same request ID and identical arguments return the existing draft; changed arguments with that ID cause a conflict. No real storage, reservation or email.
   Known request: request_id R101, book B17, quantity 2. Stock has not been checked.
   Return only one JSON object with name and arguments for the single next tool. Invent no availability or draft ID.

1. 3

   Repair a real response-format failure

   Claude first chose the correct operation, lookup_stock, but wrapped the JSON in Markdown and added explanatory prose. A human can read it; json.loads cannot parse the entire response. This observed failure concerns representation, not stock reasoning.

   The runner rejects that response instead of extracting an arbitrary brace-delimited substring. We returned the actual reason to AI: the tool choice was right, but extra text caused a JSONDecodeError. The follow-up requested one bare object and preserved the original task.

   The second recorded response contains only name and arguments. It parses to lookup_stock for B17. A focused request identifies what should change and what should remain, avoiding an unnecessary rewrite of the underlying decision.

   Parsing alone is insufficient. The program validates allowlisted names, exact argument keys and types, including integer quantities rather than strings or booleans. Place that boundary before text becomes an executable action, even when your prompt already explains the requirements.

   Compare the unchanged first response with the repaired one below. The transferable skill is diagnosing the violated contract and asking for a precise correction. Provider-supported structured outputs can help represent calls, but they do not replace checking the validity of business inputs.

   Your full response fails json.loads because of Markdown fences and trailing explanation. The lookup_stock choice is correct. Return one JSON object only, starting with { and ending with }. Include just name and arguments. Stock is still unknown. Do not execute tools.

   Unchanged first response from the recorded Korean conversation; its Markdown fences and trailing prose cause whole-response JSON parsing to fail.

   The second recorded response is:

   Second recorded response: {"name":"lookup_stock","arguments":{"book_id":"B17"}}

   Example responseCopy

   A teaching example of a workflow in an external AI tool. Results vary with the request and context.

   {
     "name": "lookup_stock",
     "arguments": {
       "book_id": "B17"
     }
   }
   

   재고 조회 결과가 아직 없으므로, 읽기 전용인 lookup_stock을 먼저 호출합니다. create_draft는 available이 수량 2권을 충족한다는 결과를 확인한 뒤에만 request_id: "R101", book_id: "B17", quantity: 2로 제안하는 것이 안전합니다.

2. 4

   Return an executed lookup before requesting a draft

   After parsing the second proposal, the editor executed local lookup_stock. It returned B17, availability 2 and a fixed fictional timestamp. This is an actual local result over teaching data, not live external stock.

   Paste that result into the same conversation, preserving the original goal. Ask for create_draft and require a note that availability applies at the checked time and no reservation is confirmed. A successful read does not establish a successful booking.

   The third recorded response uses R101, B17 and quantity 2, with a note identifying a staff-review draft. It invents no draft_id: that identifier belongs to the tool's later result, not the model's proposed input. Distinguishing inputs from outputs keeps application status honest.

   The runner requires a prior lookup and enough available copies before creating a draft. Natural-language assurances from AI cannot substitute for those recorded conditions. These are executable task boundaries rather than subjective judgments about the response.

   The same pattern can read event capacity before preparing a notice or read product facts before preparing a proposal. Supply observed results to the next request and preserve what has not yet occurred. Next we deliberately lose a reply after draft creation to examine recovery.

   The repaired JSON parsed successfully. The editor executed the local teaching lookup; it returned {"book_id":"B17","available":2,"checked_at":"2026-10-28T10:00:00+09:00"}. This is not a real stock system. The task remains a review draft for R101, B17, quantity 2. Return only the next tool JSON. Its note must retain that availability is as of the lookup time and reservation is unconfirmed. Do not claim the draft already exists.

   Unchanged third AI response: a proposal to create a draft, not a success result.

   Example responseCopy

   A teaching example of a workflow in an external AI tool. Results vary with the request and context.

   {"name":"create_draft","arguments":{"request_id":"R101","book_id":"B17","quantity":2,"note":"재고조회 시점(2026-10-28T10:00:00+09:00) 기준 2권 가용, 예약 미확정. 담당자 검토용 초안."}}

3. 5

   Recover a lost reply with the same task identity

   The runner deliberately creates the third-request draft, then raises TimeoutError before returning success. The editor observes one draft already in memory. A missing reply therefore does not establish that nothing happened.

   

   We return the observed timeout and the tool's retry contract to AI: identical arguments with the same request_id return the existing draft, while changed arguments conflict. One retry remains. AI should request the same operation rather than invent a new task identity.

   The fourth recorded response exactly preserves the third request, including its note. The runner returns DRAFT-R101 with status draft. There is one draft and three tool attempts: lookup, creation and retry. The first malformed response never reached tool execution and is not counted as an attempt.

   This repeat-safe property is called idempotency. The practical meaning is that repeating the same identified task preserves one result. Writing “avoid duplicates” in a prompt cannot implement it; application code must compare stored arguments and return the existing outcome.

   Changing quantity or note under the same ID conflicts in this exercise. A genuinely changed task needs an explicit update decision. The in-memory demo also loses its ledger at process exit, so it does not establish persistence or concurrency guarantees for production systems. It still provides a concrete way to practise communicating recovery state to AI.

   The local create_draft execution timed out after a reply was lost. AI did not receive success. The contract returns an existing draft for the same request ID and identical arguments, and conflicts on changed arguments. One retry remains. Return the prior request with request_id, book_id, quantity and note unchanged. Invent no new ID. JSON only; do not claim completion.

   Unchanged fourth response; compare its arguments with turn three.

   Editorial replay: draft_id DRAFT-R101, status draft, three tool attempts and one final draft. No real booking or message was made.

   Example responseCopy

   A teaching example of a workflow in an external AI tool. Results vary with the request and context.

   {"name":"create_draft","arguments":{"request_id":"R101","book_id":"B17","quantity":2,"note":"재고조회 시점(2026-10-28T10:00:00+09:00) 기준 2권 가용, 예약 미확정. 담당자 검토용 초안."}}

4. 6

   Inspect the complete replay and its boundaries

   The final file contains an editor-written validator and local tools plus four actual AI proposals. Its header identifies an offline text replay. A separate conversation file preserves prompts and responses, so model text can be distinguished from verification code.

   

   Running Python shows invalid_json on turn one, a stock result on turn two, a deliberately lost reply on turn three and the existing draft on turn four. The summary is three tool attempts and one draft. Explain the sequence rather than relying only on the final count.

   Try an unknown send_email name, drafting before lookup, a negative quantity and changed arguments under R101. Each must be held for a specific reason even if the JSON syntax is valid. These checks measure program boundaries independently of how well AI follows its instructions.

   The runner limits execution to four attempts. Repeating a failing request indefinitely can grow work or cost, so exceeding that limit requires review. Its final state remains draft; approval and sending are different states that this exercise does not implement.

   For a real API extension, consult the provider's tool IDs, input schemas and result-message linkage. The teaching names and arguments envelope is not a substitute for SDK fields. The transferable concepts are allowlisting, input validation, returning actual results and recovering the same identified task.

   the complete tool-workflow program

   File	Contents
   tool-workflow-recovery.py	Python 3 · four recorded proposals · local replay

   Download the complete tool-workflow program

   The editor actually executed this final flow.

   Example codeCopy

   turn 1: invalid_json turn 2: B17 available=2 turn 3: simulated_reply_lost_after_create turn 4: DRAFT-R101 status=draft tool_attempts: 3 draft_count: 1

This is a learning check, not a test you must pass. Use the explanations to understand the ideas.

1. Q1AI chose lookup_stock correctly but added prose around JSON. What should your follow-up preserve and change?

   Write your thoughts (optional)

   Write your thoughts (optional)

   Your writing is not sent anywhere. It disappears when you leave or reload this page, so copy anything you want to keep.

   Read the answer and explanation

   Preserve the operation and B17 argument while requesting one bare JSON object. Explain the actual parse failure and its extra-text cause. Reject the response before execution, so it does not count as a tool attempt.

   I read and understood the explanation

   This is your own review, not an automatic score.

2. Q2A reply was lost after draft creation. Why is inventing a new request_id risky?

   Write your thoughts (optional)

   Write your thoughts (optional)

   Your writing is not sent anywhere. It disappears when you leave or reload this page, so copy anything you want to keep.

   Read the answer and explanation

   The first draft may already exist, and a new ID can create another one. Reuse identical arguments and the same ID under a repeat-safe tool contract. A prompt alone does not implement duplicate prevention.

   I read and understood the explanation

   This is your own review, not an automatic score.

3. Q3Fresh fictional request R202 needs two B22 copies but lookup returns zero. AI proposes a zero-quantity draft. Should it be accepted?

   Write your thoughts (optional)

   Write your thoughts (optional)

   Your writing is not sent anywhere. It disappears when you leave or reload this page, so copy anything you want to keep.

   Read the answer and explanation

   Reject it. In this fictional exercise the user requested two and the allowed quantity is one through three. Explain unavailable stock and seek clarification instead of changing inputs to manufacture success.

   I read and understood the explanation

   This is your own review, not an automatic score.

4. Q4There are four AI responses, three tool attempts and one draft. Why do the counts differ?

   Write your thoughts (optional)

   Write your thoughts (optional)

   Your writing is not sent anywhere. It disappears when you leave or reload this page, so copy anything you want to keep.

   Read the answer and explanation

   The first response failed JSON validation before execution. Lookup, creation and retry made three attempts. The identical R101 retry returned the existing draft, leaving one result.

   I read and understood the explanation

   This is your own review, not an automatic score.

1. 7

   Try it: ask AI to handle an unavailable book

   The fresh task R202 requests two copies of B22; local stock for B22 is zero. Ask AI for the next operation with the new task identifiers. Before returning the lookup result, check whether it requests the read rather than inventing stock or immediately creating a draft.

   After lookup, return B22, availability zero and the checked time. Ask what can happen next and how to explain the result. Creating a draft fails the availability rule. Substituting another book or changing the requested quantity to zero does not fulfil the user's stated request.

   If AI nevertheless proposes create_draft, the runner should hold it as insufficient_stock. Return that observed failure and ask for an accurate explanation of the shortage and next clarification. Friendly wording can improve communication without changing the executable conditions.

   Separately, change R101's quantity to three while preserving its ID. The changed arguments must conflict. Determine whether the user means to revise an earlier draft or create a separate task before designing a new operation; this teaching contract has no update tool.

   Without tools, explain unavailable stock, unchanged retry arguments and validation boundaries. With tools, retain requests, responses, executed results and the final draft count. Those linked records make the path from AI suggestion to actual outcome understandable and reviewable.

   the recorded prompts and responses

   File	Contents
   tool-workflow-recovery-conversation.txt	Exact recorded Korean conversation

   Download the recorded prompts and responses