docs: Add documentation for Ollama MCP tool calling message normalization #9256
+83
−2
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…tion Document the automatic message normalization feature that fixes compatibility issues with Ollama models when using MCP tool calling: - Add comprehensive troubleshooting section for Ollama MCP issues - Document Mistral/Ministral system message reordering - Document Gemma3 index field removal - List verified working models - Add notes to Ollama guide about automatic MCP compatibility - Add brief mention in MCP deep dive documentation Relates to PR #9253 Generated with [Continue](https://continue.dev) Co-Authored-By: Continue <[email protected]> Co-authored-by: nate <[email protected]>
dosubot
bot
added
the
size:M
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR adds comprehensive documentation for the automatic message normalization feature that fixes Ollama model compatibility issues with MCP tool calling (introduced in PR #9253).
Documentation Updates
1. Troubleshooting Guide ()
Added new section "Ollama MCP tool calling issues" with:
- Explanation of automatic message normalization - **Mistral/Ministral models**: Documents the fix for "Unexpected role 'system' after role 'tool'" errors - **Gemma3 models**: Documents the fix for "Invalid 'tool_calls': unknown variant 'index'" errors - List of verified working Ollama models (DeepSeek V3.1, Qwen3, Mistral Large 3, etc.) - Cross-references to related documentation2. Ollama Guide ()
Added "MCP Tool Calling Compatibility" subsection:
Highlights that Continue automatically handles model-specific message formatting—no configuration needed by users3. MCP Deep Dive ()
Added "Model Compatibility" note:
Why These Changes?
The message normalization feature is a significant improvement that makes MCP tool calling work seamlessly with Ollama models that previously failed. Users need to know:
Documentation Approach
Used Mintlify components (Info, Warning, Accordion) to make information scannable and actionable Connected related docs (troubleshooting ↔ Ollama guide ↔ MCP guide) for easy navigation Troubleshooting = comprehensive; Ollama guide = overview; MCP = brief mention Emphasized "no action required" to reduce support burdenRelated
This agent session was co-authored by nate and Continue.
Summary by cubic
Add docs for automatic message normalization that makes MCP tool calling work reliably with Ollama models. Includes troubleshooting for Mistral/Ministral system-message ordering and Gemma3 tool_call index errors, a verified models list, an Ollama guide note that no config is needed, and a brief mention in the MCP deep dive.
Written for commit 0811b73. Summary will update automatically on new commits.