[opentelemetry-instrumentation-genai-anthropic] Record gen_ai.tool.definitions

A tool-calling request produced a span with no trace of the tools it offered
the model. extract_params reads the request arguments one by one and had no
slot for tools, so the list never reached the code that records telemetry.

Add the slot and map Anthropic's tool shapes onto the semconv models. A custom
tool carries input_schema and becomes a FunctionToolDefinition. Server tools
and toolsets become a GenericToolDefinition keyed by their versioned type; a
toolset carries no name, so its type stands in for the name the schema
requires.

Recording follows OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT, matching
genai-openai. The attribute is opt_in in spans.yaml and sits in the
attributes.gen_ai.content group.

Assisted-by: Claude Opus 5

Author: sfc-gh-zeningchen

instrumentation/opentelemetry-instrumentation-genai-anthropic/.changelog/+anthropic-tool-definitions.fixed

@@ -0,0 +1 @@
+Record ``gen_ai.tool.definitions`` from the ``tools`` request parameter.

instrumentation/opentelemetry-instrumentation-genai-anthropic/src/opentelemetry/instrumentation/genai/anthropic/messages_extractors.py

@@ -24,10 +24,13 @@
 )
 from opentelemetry.util.genai.invocation import InferenceInvocation
 from opentelemetry.util.genai.types import (
+    FunctionToolDefinition,
+    GenericToolDefinition,
     InputMessage,
     OutputMessage,
     SystemInstructionPart,
     TextPart,
+    ToolDefinition,
 )
 from opentelemetry.util.types import AttributeValue
 
@@ -63,6 +66,7 @@ class MessageRequestParams:
     stream: bool | None = None
     messages: Iterable[MessageParam] | None = None
     system: str | Iterable[TextBlockParam] | None = None
+    tools: Iterable[ToolUnionParam] | None = None
 
 
 GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS = (
@@ -138,6 +142,58 @@ def get_system_instruction(
     ]
 
 
+def _tool_field(tool: object, key: str) -> object:
+    if isinstance(tool, Mapping):
+        return cast("Mapping[str, object]", tool).get(key)
+    return getattr(tool, key, None)
+
+
+def get_tool_definitions(
+    tools: Iterable[ToolUnionParam] | None,
+) -> list[ToolDefinition] | None:
+    """Convert the request's ``tools`` into semconv tool definitions.
+
+    A custom tool carries its JSON schema in ``input_schema`` and maps onto a
+    function definition. Server tools are identified by a versioned ``type``
+    (``web_search_20250305``, ``bash_20250124``, ...) and toolsets
+    (``computer_toolset_20260801``, ...) carry no ``name`` at all, so their type
+    stands in for the name.
+    """
+    if tools is None:
+        return None
+
+    definitions: list[ToolDefinition] = []
+    for tool in tools:
+        name = _tool_field(tool, "name")
+        tool_type = _tool_field(tool, "type")
+        input_schema = _tool_field(tool, "input_schema")
+        if input_schema is not None or tool_type in (None, "custom"):
+            description = _tool_field(tool, "description")
+            definitions.append(
+                FunctionToolDefinition(
+                    name=name if isinstance(name, str) else "",
+                    description=(
+                        description if isinstance(description, str) else None
+                    ),
+                    # The schema requires an object; drop anything else rather
+                    # than emit a tool definition that fails validation.
+                    parameters=(
+                        input_schema
+                        if isinstance(input_schema, Mapping)
+                        else None
+                    ),
+                )
+            )
+        elif isinstance(tool_type, str):
+            definitions.append(
+                GenericToolDefinition(
+                    name=name if isinstance(name, str) else tool_type,
+                    type=tool_type,
+                )
+            )
+    return definitions or None
+
+
 def get_output_messages_from_message(
     message: Message | None,
 ) -> list[OutputMessage]:
@@ -244,6 +300,7 @@ def extract_params(  # pylint: disable=too-many-locals
         stream=stream,
         messages=messages,
         system=system,
+        tools=tools,
     )
 
 

instrumentation/opentelemetry-instrumentation-genai-anthropic/src/opentelemetry/instrumentation/genai/anthropic/patch.py

@@ -24,6 +24,7 @@
     get_llm_request_attributes,
     get_server_address_and_port,
     get_system_instruction,
+    get_tool_definitions,
 )
 from .utils import is_anthropic_async_stream, is_anthropic_stream
 from .wrappers import (
@@ -249,6 +250,9 @@ def _create_invocation(
     invocation.system_instruction = (
         get_system_instruction(params.system) if capture_content else []
     )
+    invocation.tool_definitions = (
+        get_tool_definitions(params.tools) if capture_content else None
+    )
     invocation.attributes = attributes
     return invocation
 

instrumentation/opentelemetry-instrumentation-genai-anthropic/tests/test_async_messages.py

@@ -87,6 +87,30 @@ def _load_span_messages(span, attribute):
     return parsed
 
 
+_WEATHER_TOOL = {
+    "name": "get_weather",
+    "description": "Get weather by city",
+    "input_schema": {
+        "type": "object",
+        "properties": {"city": {"type": "string"}},
+        "required": ["city"],
+    },
+}
+
+
+def _assert_weather_tool_definitions(span):
+    assert _load_span_messages(
+        span, GenAIAttributes.GEN_AI_TOOL_DEFINITIONS
+    ) == [
+        {
+            "type": "function",
+            "name": "get_weather",
+            "description": "Get weather by city",
+            "parameters": _WEATHER_TOOL["input_schema"],
+        }
+    ]
+
+
 class _AsyncErrorInjectingStreamDelegate:
     def __init__(self, inner):
         self._inner = inner
@@ -484,6 +508,35 @@ async def test_async_messages_create_streaming_delegates_response_attribute(
     await stream.close()
 
 
+@pytest.mark.asyncio
+@pytest.mark.vcr()
+@pytest.mark.cassette("test_async_messages_stream")
+@pytest.mark.skipif(
+    not _has_tools_param,
+    reason="anthropic SDK too old to support 'tools' parameter",
+)
+async def test_async_messages_stream_records_tool_definitions(
+    span_exporter, async_anthropic_client, instrument_with_content
+):
+    """``stream`` builds its invocation lazily -- it must still see ``tools``.
+
+    Replays the plain ``test_async_messages_stream`` cassette: tool definitions
+    come from the request, so the recorded response does not matter.
+    """
+    async with async_anthropic_client.messages.stream(
+        model="claude-sonnet-4-20250514",
+        max_tokens=100,
+        messages=[{"role": "user", "content": "Say hello in one word."}],
+        tools=[_WEATHER_TOOL],
+    ) as stream:
+        async for _ in stream:
+            pass
+
+    spans = span_exporter.get_finished_spans()
+    assert len(spans) == 1
+    _assert_weather_tool_definitions(spans[0])
+
+
 @pytest.mark.asyncio
 @pytest.mark.vcr()
 async def test_async_messages_stream(  # pylint: disable=too-many-locals
@@ -743,17 +796,7 @@ async def test_async_messages_create_captures_tool_use_content(
         model=model,
         max_tokens=256,
         messages=messages,
-        tools=[
-            {
-                "name": "get_weather",
-                "description": "Get weather by city",
-                "input_schema": {
-                    "type": "object",
-                    "properties": {"city": {"type": "string"}},
-                    "required": ["city"],
-                },
-            }
-        ],
+        tools=[_WEATHER_TOOL],
         tool_choice={"type": "tool", "name": "get_weather"},
     )
 
@@ -769,6 +812,34 @@ async def test_async_messages_create_captures_tool_use_content(
         for message in output_messages
         for part in message.get("parts", [])
     )
+    _assert_weather_tool_definitions(span)
+
+
+@pytest.mark.asyncio
+@pytest.mark.vcr()
+@pytest.mark.cassette("test_async_messages_create_captures_tool_use_content")
+@pytest.mark.skipif(
+    not _has_tools_param,
+    reason="anthropic SDK too old to support 'tools' parameter",
+)
+async def test_async_messages_create_omits_tool_definitions_without_content(
+    span_exporter, async_anthropic_client, instrument_no_content
+):
+    """Tool definitions are content: they stay off when capture is off."""
+    await async_anthropic_client.messages.create(
+        model="claude-sonnet-4-20250514",
+        max_tokens=256,
+        messages=[{"role": "user", "content": "What is the weather in SF?"}],
+        tools=[_WEATHER_TOOL],
+        tool_choice={"type": "tool", "name": "get_weather"},
+    )
+
+    spans = span_exporter.get_finished_spans()
+    assert len(spans) == 1
+    span = spans[0]
+    assert GenAIAttributes.GEN_AI_INPUT_MESSAGES not in span.attributes
+    assert GenAIAttributes.GEN_AI_OUTPUT_MESSAGES not in span.attributes
+    assert GenAIAttributes.GEN_AI_TOOL_DEFINITIONS not in span.attributes
 
 
 @pytest.mark.asyncio

instrumentation/opentelemetry-instrumentation-genai-anthropic/tests/test_messages_extractors.py

@@ -3,8 +3,15 @@
 
 """Tests for Anthropic message parameter extraction."""
 
+import pytest
+
 from opentelemetry.instrumentation.genai.anthropic.messages_extractors import (
     extract_params,
+    get_tool_definitions,
+)
+from opentelemetry.util.genai.types import (
+    FunctionToolDefinition,
+    GenericToolDefinition,
 )
 
 
@@ -47,3 +54,115 @@ def test_extract_params_ignores_non_mapping_extra_body():
     assert params.temperature is None
     assert params.top_p is None
     assert params.top_k is None
+
+
+def test_extract_params_keeps_tools():
+    tools = [{"name": "get_weather", "input_schema": {"type": "object"}}]
+
+    params = extract_params(tools=tools)
+
+    assert params.tools is tools
+
+
+def test_get_tool_definitions_maps_custom_tool_to_function():
+    schema = {
+        "type": "object",
+        "properties": {"city": {"type": "string"}},
+        "required": ["city"],
+    }
+
+    definitions = get_tool_definitions(
+        [
+            {
+                "name": "get_weather",
+                "description": "Get weather by city",
+                "input_schema": schema,
+            }
+        ]
+    )
+
+    assert definitions == [
+        FunctionToolDefinition(
+            name="get_weather",
+            description="Get weather by city",
+            parameters=schema,
+        )
+    ]
+    assert definitions[0].type == "function"
+
+
+def test_get_tool_definitions_maps_explicit_custom_type_to_function():
+    definitions = get_tool_definitions([{"type": "custom", "name": "noop"}])
+
+    assert definitions == [
+        FunctionToolDefinition(name="noop", description=None, parameters=None)
+    ]
+
+
+def test_get_tool_definitions_maps_server_tool_to_generic():
+    definitions = get_tool_definitions(
+        [
+            {
+                "name": "web_search",
+                "type": "web_search_20250305",
+                "max_uses": 3,
+            }
+        ]
+    )
+
+    assert definitions == [
+        GenericToolDefinition(name="web_search", type="web_search_20250305")
+    ]
+
+
+def test_get_tool_definitions_falls_back_to_type_for_unnamed_toolset():
+    definitions = get_tool_definitions(
+        [{"type": "computer_toolset_20260801", "configs": []}]
+    )
+
+    assert definitions == [
+        GenericToolDefinition(
+            name="computer_toolset_20260801",
+            type="computer_toolset_20260801",
+        )
+    ]
+
+
+def test_get_tool_definitions_reads_tool_objects():
+    class _Tool:
+        name = "get_weather"
+        description = "Get weather by city"
+        input_schema = {"type": "object"}
+
+    definitions = get_tool_definitions([_Tool()])
+
+    assert definitions == [
+        FunctionToolDefinition(
+            name="get_weather",
+            description="Get weather by city",
+            parameters={"type": "object"},
+        )
+    ]
+
+
+def test_get_tool_definitions_mixes_custom_and_server_tools():
+    definitions = get_tool_definitions(
+        [
+            {"name": "get_weather", "input_schema": {"type": "object"}},
+            {"name": "bash", "type": "bash_20250124"},
+        ]
+    )
+
+    assert definitions == [
+        FunctionToolDefinition(
+            name="get_weather",
+            description=None,
+            parameters={"type": "object"},
+        ),
+        GenericToolDefinition(name="bash", type="bash_20250124"),
+    ]
+
+
+@pytest.mark.parametrize("tools", [None, []])
+def test_get_tool_definitions_without_tools(tools):
+    assert get_tool_definitions(tools) is None