Python: Require tool_call_id parameter for string-based tool messages in ChatHistory

[moonbox3]

Motivation and Context

The add_tool_message method of ChatHistory accepts string content without requiring a tool_call_id parameter. This design is flawed from an API design perspective. It created tool messages that:

1. Violated chat completion protocols: most LLM APIs (OpenAI, etc.) require tool messages to have a tool_call_id that references a previous function call
2. Broke conversation flow: tool messages should always be responses to specific tool calls, maintaining the call-response relationship
3. Created malformed message sequences: messages without proper tool call IDs would fail when sent to language models

Description

This PR modifies the add_tool_message string overload to require a tool_call_id parameter, which makes sure we have proper tool call protocol compliance.

1. The string overload now validates that tool_call_id is provided and raises a clear error if missing
2. Tool messages now create FunctionResultContent objects with both id and call_id set to the provided tool_call_id
3. Added support for an optional function_name parameter for better bookkeeping
4. Provides informative error messages explaining why tool_call_id is required

• Closes Python: Bug: adding TOOL message to ChatHistory causes validation error in ChatMessageContent #12744

Before:

# This would create an invalid tool message without tool_call_id
# when the `.to_dict()` method is called on `ChatMessageContent`
chat_history.add_tool_message("Function result")  # Creates broken message and losing pairing to the corresponding `FunctionCallContent`.

After:

# Now requires tool_call_id for proper protocol compliance
chat_history.add_tool_message("Function result")  # raises clear error due to missing `tool_call_id`
chat_history.add_tool_message("Function result", tool_call_id="call_123")  # works correctly

# Optional function name for better bookkeeping
chat_history.add_tool_message("Function result", tool_call_id="call_123", function_name="get_weather") # works as well

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the SK Contribution Guidelines and the pre-submission formatting script raises no violations
• All unit tests pass, and I have added new tests where possible
• I didn't break anyone 😄

[moonbox3]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
contents
chat_history.py	181	4	97%	103, 108, 309–310
TOTAL	26679	4580	82%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
3659	22 💤	0 ❌	0 🔥	1m 53s ⏱️

[mattiasu96]

Small comment, could be nice to also add an utility function to add function call messages?

At the moment the library provides convenience methods for user, system and tool result, it would be consistent with the rest to also have a function to explicitly manage tool call messages in the chat history (besides using the standard add_message function)

[moonbox3]

Small comment, could be nice to also add an utility function to add function call messages?

At the moment the library provides convenience methods for user, system and tool result, it would be consistent with the rest to also have a function to explicitly manage tool call messages in the chat history (besides using the standard add_message function)

Thanks for the feedback. We can look into this in the next iteration.