docs(ai_client): add SQLite-granularity docstrings to tool execution functions

Also fixes return-type discrepancy in tests/test_ai_client_tool_loop.py mock by wrapping NormalizedResponse inside Result.

tests/test_ai_client_tool_loop.py

@@ -16,6 +16,7 @@ from __future__ import annotations
 from typing import Any
 from unittest.mock import MagicMock, patch
 import pytest
+from src.result_types import Result
 from src.openai_compatible import NormalizedResponse, OpenAICompatibleRequest
 from src.ai_client import run_with_tool_loop
 from src.vendor_capabilities import VendorCapabilities
@@ -24,13 +25,13 @@ from src.vendor_capabilities import VendorCapabilities
 def caps() -> VendorCapabilities:
  return VendorCapabilities(vendor="test", model="test-model", tool_calling=True, context_window=8192)
 
-def _make_normalized_response(text: str = "ok", tool_calls: list[dict[str, Any]] | None = None) -> NormalizedResponse:
- return NormalizedResponse(
+def _make_normalized_response(text: str = "ok", tool_calls: list[dict[str, Any]] | None = None) -> Result[NormalizedResponse]:
+ return Result(data=NormalizedResponse(
   text=text, tool_calls=tool_calls or [],
   usage_input_tokens=10, usage_output_tokens=5,
   usage_cache_read_tokens=0, usage_cache_creation_tokens=0,
   raw_response=None,
- )
+ ))
 
 def test_run_with_tool_loop_no_tool_calls_returns_immediately(caps: VendorCapabilities) -> None:
  client = MagicMock()