polish description and add models

Change-Id: Ib6133b3019195e4fa9a54d329ff4b891a281d208
Co-developed-by: Cursor <[email protected]>

Author: Cirilla-zmh

.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

@@ -204,13 +204,10 @@ 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 of the definition objects
-by default. Otherwise, it's NOT RECOMMENDED to populate it by default.
+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.
 
-> [!Warning]
-> This attribute is likely to contain sensitive information including user/PII data.
-
 ---
 
 `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

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

@@ -205,13 +205,10 @@ 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 of the definition objects
-by default. Otherwise, it's NOT RECOMMENDED to populate it by default.
+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.
 
-> [!Warning]
-> This attribute is likely to contain sensitive information including user/PII data.
-
 ---
 
 `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

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

@@ -344,13 +344,10 @@ 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 of the definition objects
-by default. Otherwise, it's NOT RECOMMENDED to populate it by default.
+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.
 
-> [!Warning]
-> This attribute is likely to contain sensitive information including user/PII data.
-
 ---
 
 `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

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

@@ -185,13 +185,10 @@ 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 of the definition objects
-by default. Otherwise, it's NOT RECOMMENDED to populate it by default.
+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.
 
-> [!Warning]
-> This attribute is likely to contain sensitive information including user/PII data.
-
 ---
 
 `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

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

@@ -217,13 +217,10 @@ 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 of the definition objects
-by default. Otherwise, it's NOT RECOMMENDED to populate it by default.
+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.
 
-> [!Warning]
-> This attribute is likely to contain sensitive information including user/PII data.
-
 ---
 
 `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

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

@@ -22,6 +22,7 @@
                     "type": "string"
                 },
                 "description": {
+                    "default": null,
                     "description": "Description of the tool.",
                     "title": "Description",
                     "type": "string"
@@ -39,8 +40,7 @@
             },
             "required": [
                 "type",
-                "name",
-                "description"
+                "name"
             ],
             "title": "ToolDefinition",
             "type": "object"

docs/gen-ai/non-normative/models.ipynb

@@ -251,7 +251,7 @@
     "    \"\"\"\n",
     "    type: Union[ToolType, str] = Field(description=\"Type of the tool.\")\n",
     "    name: str = Field(description=\"Name of the tool.\")\n",
-    "    description: str = Field(description=\"Description of the tool.\")\n",
+    "    description: str = Field(None, description=\"Description of the tool.\")\n",
     "    parameters: Any = Field(\n",
     "        default=None,\n",
     "        description=(\n",
@@ -283,7 +283,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "semconv",
+   "display_name": "Python 3",
    "language": "python",
    "name": "python3"
   },

docs/gen-ai/openai.md

@@ -210,13 +210,10 @@ 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 of the definition objects
-by default. Otherwise, it's NOT RECOMMENDED to populate it by default.
+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.
 
-> [!Warning]
-> This attribute is likely to contain sensitive information including user/PII data.
-
 ---
 
 `error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

docs/registry/attributes/gen-ai.md

@@ -167,13 +167,10 @@ 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 of the definition objects
-by default. Otherwise, it's NOT RECOMMENDED to populate it by default.
+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.
 
-> [!Warning]
-> This attribute is likely to contain sensitive information including user/PII data.
-
 **[13] `gen_ai.tool.type`:** Extension: A tool executed on the agent-side to directly call external APIs, bridging the gap between the agent and real-world systems.
   Agent-side operations involve actions that are performed by the agent on the server or within the agent's controlled environment.
 Function: A tool executed on the client-side, where the agent generates parameters for a predefined function, and the client executes the logic.