Address PR review comments

- Rename anthropic_cache_tools to anthropic_cache_tool_definitions for clarity
- Add backticks to docstrings for code identifiers (cache_control, tools)
- Improve error message to mention alternative cache settings
- Remove unnecessary cast for BetaToolUnionParam (line 441)
- Add explanatory comment for necessary cast of BetaContentBlockParam (line 703)
- Update Bedrock comment to link to issue #3418

All tests pass with these changes.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: ronakrm

docs/models/anthropic.md

@@ -124,7 +124,7 @@ async def main():
 
 ### 3. Cache Tool Definitions
 
-Use `anthropic_cache_tools=True` to cache your tool definitions:
+Use `anthropic_cache_tool_definitions=True` to cache your tool definitions:
 
 ```python {test="skip"}
 from pydantic_ai import Agent
@@ -133,7 +133,7 @@ from pydantic_ai.models.anthropic import AnthropicModelSettings
 agent = Agent(
     'anthropic:claude-sonnet-4-5',
     model_settings=AnthropicModelSettings(
-        anthropic_cache_tools=True
+        anthropic_cache_tool_definitions=True
     ),
 )
 
@@ -160,7 +160,7 @@ agent = Agent(
     system_prompt='Detailed instructions...',
     model_settings=AnthropicModelSettings(
         anthropic_cache_instructions=True,
-        anthropic_cache_tools=True,
+        anthropic_cache_tool_definitions=True,
     ),
 )
 

pydantic_ai_slim/pydantic_ai/models/anthropic.py

@@ -150,10 +150,10 @@ class AnthropicModelSettings(ModelSettings, total=False):
     See [the Anthropic docs](https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking) for more information.
     """
 
-    anthropic_cache_tools: bool
-    """Whether to add cache_control to the last tool definition.
+    anthropic_cache_tool_definitions: bool
+    """Whether to add `cache_control` to the last tool definition.
 
-    When enabled, the last tool in the tools array will have cache_control set,
+    When enabled, the last tool in the `tools` array will have `cache_control` set,
     allowing Anthropic to cache tool definitions and reduce costs.
     See https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching for more information.
     """
@@ -437,8 +437,8 @@ def _get_tools(
         ]
 
         # Add cache_control to the last tool if enabled
-        if tools and model_settings.get('anthropic_cache_tools'):
-            last_tool = cast(dict[str, Any], tools[-1])
+        if tools and model_settings.get('anthropic_cache_tool_definitions'):
+            last_tool = tools[-1]
             last_tool['cache_control'] = BetaCacheControlEphemeralParam(type='ephemeral')
 
         return tools
@@ -692,13 +692,16 @@ def _add_cache_control_to_last_param(params: list[BetaContentBlockParam]) -> Non
         """
         if not params:
             raise UserError(
-                'CachePoint cannot be the first content in a user message - there must be previous content to attach the CachePoint to.'
+                'CachePoint cannot be the first content in a user message - there must be previous content to attach the CachePoint to. '
+                'To cache system instructions or tool definitions, use the `anthropic_cache_instructions` or `anthropic_cache_tool_definitions` settings instead.'
             )
 
         # Only certain types support cache_control
         # See https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching#what-can-be-cached
         cacheable_types = {'text', 'tool_use', 'server_tool_use', 'image', 'tool_result'}
-        last_param = cast(dict[str, Any], params[-1])  # Cast to dict for mutation
+        # Cast needed because BetaContentBlockParam is a union including response Block types (Pydantic models)
+        # that don't support dict operations, even though at runtime we only have request Param types (TypedDicts).
+        last_param = cast(dict[str, Any], params[-1])
         if last_param['type'] not in cacheable_types:
             raise UserError(f'Cache control not supported for param type: {last_param["type"]}')
 

tests/models/test_anthropic.py

@@ -429,7 +429,7 @@ def test_cache_control_unsupported_param_type():
 
 
 async def test_anthropic_cache_tools(allow_model_requests: None):
-    """Test that anthropic_cache_tools adds cache_control to last tool."""
+    """Test that anthropic_cache_tool_definitions adds cache_control to last tool."""
     c = completion_message(
         [BetaTextBlock(text='Tool result', type='text')],
         usage=BetaUsage(input_tokens=10, output_tokens=5),
@@ -439,7 +439,7 @@ async def test_anthropic_cache_tools(allow_model_requests: None):
     agent = Agent(
         m,
         system_prompt='Test system prompt',
-        model_settings=AnthropicModelSettings(anthropic_cache_tools=True),
+        model_settings=AnthropicModelSettings(anthropic_cache_tool_definitions=True),
     )
 
     @agent.tool_plain
@@ -514,7 +514,7 @@ async def test_anthropic_cache_tools_and_instructions(allow_model_requests: None
         m,
         system_prompt='System instructions to cache.',
         model_settings=AnthropicModelSettings(
-            anthropic_cache_tools=True,
+            anthropic_cache_tool_definitions=True,
             anthropic_cache_instructions=True,
         ),
     )