Add JSON Schema Definition for gen_ai.tool.definitions

.chloggen/schema_of_gen_ai_tool_definitions.yaml

@@ -0,0 +1,26 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: gen-ai
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Enhance the definition of `gen_ai.tool.definitions` attribute.
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [2721, 1835]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext: |
+  The schema of `gen_ai.tool.definitions` attribute is now enhanced to:
+  - Add JSON schema of `gen_ai.tool.definitions` attribute.
+  - Document the behavior of capturing tool definitions.
+  - Capture the tool definitions in a simplified format if the content capturing is disabled.

docs/gen-ai/aws-bedrock.md

@@ -194,13 +194,19 @@ section for more details.
 
 **[14] `gen_ai.tool.definitions`:** The value of this attribute matches source system tool definition format.
 
-It's expected to be an array of objects where each object represents a tool definition. In case a serialized string is available
-to the instrumentation, the instrumentation SHOULD do the best effort to
-deserialize it to an array. When recorded on spans, it MAY be recorded as a JSON string if structured format is not supported and SHOULD be recorded in structured form otherwise.
+It's expected to be an array of objects, each representing a tool definition,
+and the structure of the array is expected to match the [Tool Definitions JSON Schema](/docs/gen-ai/gen-ai-tool-definitions.json).
+In case a serialized string is available to the instrumentation, the instrumentation
+SHOULD do the best effort to deserialize it to an array.
 
-Since this attribute could be large, it's NOT RECOMMENDED to populate
-it by default. Instrumentations MAY provide a way to enable
-populating this attribute.
+When the attribute is recorded on events, it MUST be recorded in structured
+form. When recorded on spans, it MAY be recorded as a JSON string if structured
+format is not supported and SHOULD be recorded in structured form otherwise.
+
+If instrumentations can reliably deserialize and extract the tool definitions,
+it's RECOMMENDED to only populate required fields (`name`, `type`) of the definition
+objects by default. Otherwise, it's NOT RECOMMENDED to populate it by default.
+Instrumentations MAY provide a way to enable populating this attribute.
 
 ---
 

docs/gen-ai/azure-ai-inference.md

@@ -195,13 +195,19 @@ section for more details.
 
 **[14] `gen_ai.tool.definitions`:** The value of this attribute matches source system tool definition format.
 
-It's expected to be an array of objects where each object represents a tool definition. In case a serialized string is available
-to the instrumentation, the instrumentation SHOULD do the best effort to
-deserialize it to an array. When recorded on spans, it MAY be recorded as a JSON string if structured format is not supported and SHOULD be recorded in structured form otherwise.
+It's expected to be an array of objects, each representing a tool definition,
+and the structure of the array is expected to match the [Tool Definitions JSON Schema](/docs/gen-ai/gen-ai-tool-definitions.json).
+In case a serialized string is available to the instrumentation, the instrumentation
+SHOULD do the best effort to deserialize it to an array.
 
-Since this attribute could be large, it's NOT RECOMMENDED to populate
-it by default. Instrumentations MAY provide a way to enable
-populating this attribute.
+When the attribute is recorded on events, it MUST be recorded in structured
+form. When recorded on spans, it MAY be recorded as a JSON string if structured
+format is not supported and SHOULD be recorded in structured form otherwise.
+
+If instrumentations can reliably deserialize and extract the tool definitions,
+it's RECOMMENDED to only populate required fields (`name`, `type`) of the definition
+objects by default. Otherwise, it's NOT RECOMMENDED to populate it by default.
+Instrumentations MAY provide a way to enable populating this attribute.
 
 ---
 

docs/gen-ai/gen-ai-agent-spans.md

@@ -334,13 +334,19 @@ section for more details.
 
 **[15] `gen_ai.tool.definitions`:** The value of this attribute matches source system tool definition format.
 
-It's expected to be an array of objects where each object represents a tool definition. In case a serialized string is available
-to the instrumentation, the instrumentation SHOULD do the best effort to
-deserialize it to an array. When recorded on spans, it MAY be recorded as a JSON string if structured format is not supported and SHOULD be recorded in structured form otherwise.
+It's expected to be an array of objects, each representing a tool definition,
+and the structure of the array is expected to match the [Tool Definitions JSON Schema](/docs/gen-ai/gen-ai-tool-definitions.json).
+In case a serialized string is available to the instrumentation, the instrumentation
+SHOULD do the best effort to deserialize it to an array.
 
-Since this attribute could be large, it's NOT RECOMMENDED to populate
-it by default. Instrumentations MAY provide a way to enable
-populating this attribute.
+When the attribute is recorded on events, it MUST be recorded in structured
+form. When recorded on spans, it MAY be recorded as a JSON string if structured
+format is not supported and SHOULD be recorded in structured form otherwise.
+
+If instrumentations can reliably deserialize and extract the tool definitions,
+it's RECOMMENDED to only populate required fields (`name`, `type`) of the definition
+objects by default. Otherwise, it's NOT RECOMMENDED to populate it by default.
+Instrumentations MAY provide a way to enable populating this attribute.
 
 ---
 

docs/gen-ai/gen-ai-events.md

@@ -175,13 +175,19 @@ section for more details.
 
 **[13] `gen_ai.tool.definitions`:** The value of this attribute matches source system tool definition format.
 
-It's expected to be an array of objects where each object represents a tool definition. In case a serialized string is available
-to the instrumentation, the instrumentation SHOULD do the best effort to
-deserialize it to an array. When recorded on spans, it MAY be recorded as a JSON string if structured format is not supported and SHOULD be recorded in structured form otherwise.
+It's expected to be an array of objects, each representing a tool definition,
+and the structure of the array is expected to match the [Tool Definitions JSON Schema](/docs/gen-ai/gen-ai-tool-definitions.json).
+In case a serialized string is available to the instrumentation, the instrumentation
+SHOULD do the best effort to deserialize it to an array.
 
-Since this attribute could be large, it's NOT RECOMMENDED to populate
-it by default. Instrumentations MAY provide a way to enable
-populating this attribute.
+When the attribute is recorded on events, it MUST be recorded in structured
+form. When recorded on spans, it MAY be recorded as a JSON string if structured
+format is not supported and SHOULD be recorded in structured form otherwise.
+
+If instrumentations can reliably deserialize and extract the tool definitions,
+it's RECOMMENDED to only populate required fields (`name`, `type`) of the definition
+objects by default. Otherwise, it's NOT RECOMMENDED to populate it by default.
+Instrumentations MAY provide a way to enable populating this attribute.
 
 ---
 

docs/gen-ai/gen-ai-spans.md

@@ -207,13 +207,19 @@ section for more details.
 
 **[14] `gen_ai.tool.definitions`:** The value of this attribute matches source system tool definition format.
 
-It's expected to be an array of objects where each object represents a tool definition. In case a serialized string is available
-to the instrumentation, the instrumentation SHOULD do the best effort to
-deserialize it to an array. When recorded on spans, it MAY be recorded as a JSON string if structured format is not supported and SHOULD be recorded in structured form otherwise.
+It's expected to be an array of objects, each representing a tool definition,
+and the structure of the array is expected to match the [Tool Definitions JSON Schema](/docs/gen-ai/gen-ai-tool-definitions.json).
+In case a serialized string is available to the instrumentation, the instrumentation
+SHOULD do the best effort to deserialize it to an array.
+
+When the attribute is recorded on events, it MUST be recorded in structured
+form. When recorded on spans, it MAY be recorded as a JSON string if structured
+format is not supported and SHOULD be recorded in structured form otherwise.
 
-Since this attribute could be large, it's NOT RECOMMENDED to populate
-it by default. Instrumentations MAY provide a way to enable
-populating this attribute.
+If instrumentations can reliably deserialize and extract the tool definitions,
+it's RECOMMENDED to only populate required fields (`name`, `type`) of the definition
+objects by default. Otherwise, it's NOT RECOMMENDED to populate it by default.
+Instrumentations MAY provide a way to enable populating this attribute.
 
 ---
 

docs/gen-ai/gen-ai-tool-definitions.json

@@ -0,0 +1,84 @@
+{
+    "$defs": {
+        "FunctionToolDefinition": {
+            "additionalProperties": true,
+            "description": "Represents a tool definition in the form of a function.",
+            "properties": {
+                "type": {
+                    "const": "function",
+                    "description": "The type of the tool.",
+                    "title": "Type",
+                    "type": "string"
+                },
+                "name": {
+                    "description": "The name of the tool.",
+                    "title": "Name",
+                    "type": "string"
+                },
+                "description": {
+                    "default": null,
+                    "description": "The description of the tool.",
+                    "title": "Description",
+                    "type": "string"
+                },
+                "parameters": {
+                    "default": null,
+                    "description": "Schema that defines the parameters accepted by the tool. The RECOMMENDED format is JSON Schema.",
+                    "title": "Parameters"
+                },
+                "response": {
+                    "default": null,
+                    "description": "Schema that defines the response returned by the tool. The RECOMMENDED format is JSON Schema.",
+                    "title": "Response"
+                }
+            },
+            "required": [
+                "type",
+                "name"
+            ],
+            "title": "FunctionToolDefinition",
+            "type": "object"
+        },
+        "GenericToolDefinition": {
+            "additionalProperties": true,
+            "description": "Represents a tool definition in any forms.",
+            "properties": {
+                "type": {
+                    "description": "The type of the tool.",
+                    "title": "Type",
+                    "type": "string"
+                },
+                "name": {
+                    "description": "The name of the tool.",
+                    "title": "Name",
+                    "type": "string"
+                },
+                "description": {
+                    "default": null,
+                    "description": "The description of the tool.",
+                    "title": "Description",
+                    "type": "string"
+                }
+            },
+            "required": [
+                "type",
+                "name"
+            ],
+            "title": "GenericToolDefinition",
+            "type": "object"
+        }
+    },
+    "description": "Represents the list of tool definitions available to the GenAI agent or model.",
+    "items": {
+        "anyOf": [
+            {
+                "$ref": "#/$defs/FunctionToolDefinition"
+            },
+            {
+                "$ref": "#/$defs/GenericToolDefinition"
+            }
+        ]
+    },
+    "title": "ToolDefinitions",
+    "type": "array"
+}

docs/gen-ai/non-normative/examples-llm-calls.md

@@ -248,6 +248,18 @@ They are likely to be siblings if there is an encompassing span.
 | `gen_ai.usage.output_tokens`    | `17`                                        |
 | `gen_ai.usage.input_tokens`     | `47`                                        |
 | `gen_ai.response.finish_reasons`| `["tool_calls"]`                            |
+| `gen_ai.tool.definitions`       | [`gen_ai.tool.definitions`](#gen-ai-tool-definitions-tool-call-span-0) |
+
+<span id="gen-ai-tool-definitions-tool-call-span-0">`gen_ai.tool.definitions` value</span>
+
+```json
+[
+  {
+    "type": "function",
+    "name": "get_weather"
+  }
+]
+```
 
 **Tool call:**
 
@@ -298,6 +310,7 @@ They are likely to be siblings if there is an encompassing span.
 | `gen_ai.response.finish_reasons`| `["tool_calls"]`                            |
 | `gen_ai.input.messages`         | [`gen_ai.input.messages`](#gen-ai-input-messages-tool-call-span-1) |
 | `gen_ai.output.messages`        | [`gen_ai.output.messages`](#gen-ai-output-messages-tool-call-span-1) |
+| `gen_ai.tool.definitions`       | [`gen_ai.tool.definitions`](#gen-ai-tool-definitions-tool-call-span-1) |
 
 <span id="gen-ai-input-messages-tool-call-span-1">`gen_ai.input.messages` value</span>
 
@@ -336,6 +349,30 @@ They are likely to be siblings if there is an encompassing span.
 ]
 ```
 
+<span id="gen-ai-tool-definitions-tool-call-span-1">`gen_ai.tool.definitions` value</span>
+
+```json
+[
+  {
+    "type": "function",
+    "name": "get_weather",
+    "description": "Get the weather in a given location",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "location": {
+          "type": "string",
+          "description": "The city and state, e.g. San Francisco, CA"
+        },
+        "required": [
+          "location"
+        ]
+      }
+    }
+  }
+]
+```
+
 **Tool call:**
 
 If tool call is [instrumented according to execute-tool span definition](../gen-ai-spans.md#execute-tool-span), it may look like this: