docs(providers): clarify local model tool calls

[cyq1017]

Summary:

• explain that CodeWhale executes provider-returned Chat Completions tool_calls, not JSON printed as assistant text
• add local/OpenAI-compatible troubleshooting checks for endpoints and models that do not call tools
• keep provider routing and runtime behavior unchanged

Validation:

• python3 scripts/check-provider-registry.py
• git diff --check

Refs #2361

Greptile Summary

This PR adds a new "When a Local Model Prints Tool JSON" subsection to docs/PROVIDERS.md, explaining that CodeWhale only executes tools from tool_calls in Chat Completions responses, not from JSON text that a model prints inline as assistant prose. No runtime or provider-routing code is changed.

• Adds a clear explanation of the tool_calls / delta.tool_calls execution contract and why arbitrary JSON text in an assistant message is not treated as a tool request.
• Adds an actionable troubleshooting checklist covering endpoint compatibility, model/template configuration, and compatibility-layer stripping of the tools array.

Confidence Score: 5/5

This is a documentation-only change with no modifications to provider routing, tool execution, or runtime behaviour — safe to merge.

The change adds a single new documentation subsection. The technical description of the tool_calls contract is accurate, the troubleshooting checklist is actionable, and placement in the document is coherent. Nothing in the diff touches executable code.

No files require special attention.

Important Files Changed

Filename	Overview
docs/PROVIDERS.md	Documentation-only addition of a local-model tool-call troubleshooting section; no logic changes, placement is logical, and the technical assertions are accurate.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[CodeWhale sends /v1/chat/completions\nwith tools array] --> B{Provider response\ncontains tool_calls?}
    B -- Yes: tool_calls / delta.tool_calls --> C[CodeWhale executes tool\nand returns result]
    B -- No: plain JSON text\nin assistant message --> D[Treated as ordinary\nmodel output — ignored]
    D --> E[Troubleshooting]
    E --> F[Check endpoint accepts tools array]
    E --> G[Check model/chat template supports function calls]
    E --> H[Check server returns tool_calls not plain JSON]
    E --> I[Check compatibility layer does not strip tools]

Loading

_{Reviews (1): Last reviewed commit: "docs(providers): clarify local model too..." | Re-trigger Greptile}

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[Hmbown]

Harvested into #2504 as 5a909eea4 for v0.8.50 triage.

This is a docs-only clarification for #2361: local/OpenAI-compatible models need to return Chat Completions tool_calls / delta.tool_calls; JSON printed as assistant text remains ordinary model output and is not executed. Local verification on the harvest branch:

• python3 scripts/check-provider-registry.py
• git diff --check
• ./scripts/release/check-versions.sh

Thanks @cyq1017.