Explain internal vs user-controlled tool execution and the returnDirect option. When would you disable internal execution?

## Two execution modes ### Internal (default) With default options, when the model requests a tool, Spring's `ToolCallingManager` immediately executes it and re-invokes the model with the result, repeating until the model stops requesting tools. From the caller's view it's one `.call().content()` that returns final text. This is what you want most of the time. ### User-controlled Set on the options: ```java ChatOptions opts = ToolCallingChatOptions.builder() .toolCallbacks(myCallbacks) .internalToolExecutionEnabled(false) .build(); ChatResponse resp = chatModel.call(new Prompt("...", opts)); ``` Now Spring does **not** execute the tools. The `ChatResponse` contains the model's **tool-call requests** (name + arguments). You inspect them and decide what to do: - run them yourself, then build the tool-response messages and call the model again; - or delegate to `ToolCallingManager.executeToolCalls(prompt, response)` which runs them and returns updated conversation state you resubmit. **When to disable internal execution:** - **Human-in-the-loop / approval** — a person must approve a destructive action (refund, delete) before it runs. - **Distributed execution** — the tool must run in a different service, process, or security context. - **Custom orchestration** — you need explicit transaction boundaries, retries, rate-limiting, or auditing around each tool call. - **Async / deferred** — the action can't complete synchronously within the chat round-trip. ## returnDirect `@Tool(returnDirect = true)` (or `returnDirect(true)` on a programmatic callback) changes what happens **after** a tool runs: instead of feeding the result back to the model to continue reasoning, Spring returns the tool's result **directly to the caller** and ends the loop. Use it when: - The tool output *is* the final answer (e.g. a generated report, a booking id, structured data the client will render) and you don't want the model to paraphrase or hallucinate around it. - You want to **save a model round-trip** (cost/latency) since re-calling the model is unnecessary. - You need the **exact, unaltered** tool output preserved. Contrast: with the default `returnDirect=false`, the result re-enters the conversation and the model produces the user-facing text. Note: if the model requests several tools in one turn and any has `returnDirect=true`, the loop terminates and those direct results are returned — design accordingly. ## How they combine - Internal + `returnDirect=false` (default): fully automatic, model writes the final answer. - Internal + `returnDirect=true`: Spring runs the tool automatically but returns its raw result, skipping the final model call. - User-controlled: you run tools yourself regardless of `returnDirect`. ## Gotchas - Disabling internal execution means **you** own the loop — forgetting to resubmit leaves the conversation stuck at the tool-request stage. - `returnDirect=true` bypasses the model's ability to format/summarize; the caller must handle raw tool output. - With user-controlled mode you must faithfully attach tool results to the right tool-call IDs, or the follow-up model call will be inconsistent. - These are per-options/per-tool settings, not global model behavior — set them where they apply.