Skip to content

Add JSON Schema Definition for gen_ai.tool.definitions #2942

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
Open

Add JSON Schema Definition for gen_ai.tool.definitions #2942

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
391f881
Add json schema of gen ai tool definitions
Cirilla-zmh Sep 22, 2025
2c76210
polish the schema of tool definitions
Cirilla-zmh Oct 15, 2025
8562a82
feedback
Cirilla-zmh Oct 20, 2025
2a15973
polish description and add models
Cirilla-zmh Oct 20, 2025
45405a6
typo
Cirilla-zmh Oct 20, 2025
f09e9f0
feedback
Cirilla-zmh Nov 11, 2025
7060fa6
reset display name
Cirilla-zmh Nov 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions .chloggen/schema_of_gen_ai_tool_definitions.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# Use this changelog template to create an entry for release notes.
Copy link

@DylanRussell DylanRussell Nov 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For google-genai it's possible to pass a tool to the model which is just a description of the function and it's parameters, and then in the response the model will say whether and how the application can invoke the function -- see https://googleapis.github.io/python-genai/#manually-declare-and-invoke-a-function-for-function-calling -- i'm wondering if and how we should capture this type of tool definition ?

Copy link
Member Author

@Cirilla-zmh Cirilla-zmh Nov 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@DylanRussell Sure, that's the common way to request model with tools definitions. So for instrumentations, I believe we should wrap the LLM invocation and you will capture the tools definitions as the parameters in your decorator.

For example:

# you could wrap this function, and capture 'tools' from 'config' in kwargs
response = client.models.generate_content( 
    model='gemini-2.5-flash',
    contents='What is the weather like in Boston?',
    config=types.GenerateContentConfig(
        tools=[tool],
    ),
)

#
# 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.
18 changes: 12 additions & 6 deletions docs/gen-ai/aws-bedrock.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

---

Expand Down
18 changes: 12 additions & 6 deletions docs/gen-ai/azure-ai-inference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

---

Expand Down
18 changes: 12 additions & 6 deletions docs/gen-ai/gen-ai-agent-spans.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

---

Expand Down
18 changes: 12 additions & 6 deletions docs/gen-ai/gen-ai-events.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

---

Expand Down
18 changes: 12 additions & 6 deletions docs/gen-ai/gen-ai-spans.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

---

Expand Down
63 changes: 63 additions & 0 deletions docs/gen-ai/gen-ai-tool-definitions.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
{
"$defs": {
"ToolDefinition": {
"additionalProperties": true,
"description": "Represents a tool definition.",
"properties": {
"type": {
"anyOf": [
{
"$ref": "#/$defs/ToolType"
},
{
"type": "string"
}
],
"description": "Type of the tool.",
"title": "Type"
},
"name": {
"description": "Name of the tool.",
"title": "Name",
"type": "string"
},
"description": {
"default": null,
"description": "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": "ToolDefinition",
"type": "object"
},
"ToolType": {
"enum": [
"function",
"custom"
],
"title": "ToolType",
"type": "string"
}
},
"description": "Represents the list of tool definitions available to the GenAI agent or model.",
"items": {
"$ref": "#/$defs/ToolDefinition"
},
"title": "ToolDefinitions",
"type": "array"
}
37 changes: 37 additions & 0 deletions docs/gen-ai/non-normative/examples-llm-calls.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:**

Expand Down Expand Up @@ -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>

Expand Down Expand Up @@ -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:
Expand Down
63 changes: 60 additions & 3 deletions docs/gen-ai/non-normative/models.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@
},
{
"cell_type": "code",
"execution_count": 1,
"execution_count": null,
"id": "5124fe15",
"metadata": {},
"outputs": [],
Expand All @@ -68,7 +68,7 @@
" type: Literal[\"tool_call\"] = Field(description=\"The type of the content captured in this part.\")\n",
" id: Optional[str] = Field(default=None, description=\"Unique identifier for the tool call.\")\n",
" name: str = Field(description=\"Name of the tool.\")\n",
" arguments: Any = Field(None, description=\"Arguments for the tool call.\")\n",
" arguments: Any = Field(default=None, description=\"Arguments for the tool call.\")\n",
"\n",
" class Config:\n",
" extra = \"allow\"\n",
Expand Down Expand Up @@ -222,6 +222,63 @@
"# Print the JSON schema for the SystemInstructions model\n",
"print(json.dumps(SystemInstructions.model_json_schema(), indent=4))"
]
},
{
"cell_type": "markdown",
"id": "f019c33a",
"metadata": {},
"source": [
"## `gen_ai.tool.definitions` model\n",
"\n",
"Corresponding attribute: [`gen_ai.tool.definitions`](/docs/registry/attributes/gen-ai.md#gen-ai-tool-definitions).\n",
"JSON schema: [`gen_ai-tool-definitions.json`](../gen-ai-tool-definitions.json)"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "a9e84726",
"metadata": {},
"outputs": [],
"source": [
"class ToolType(str, Enum):\n",
" FUNCTION = \"function\"\n",
" CUSTOM = \"custom\"\n",
"\n",
"class ToolDefinition(BaseModel):\n",
" \"\"\"\n",
" Represents a tool definition.\n",
" \"\"\"\n",
" type: Union[ToolType, str] = Field(description=\"Type of the tool.\")\n",
" name: str = Field(description=\"Name of the tool.\")\n",
" description: str = Field(None, description=\"Description of the tool.\")\n",
" parameters: Any = Field(\n",
" default=None,\n",
" description=(\n",
" \"Schema that defines the parameters accepted by the tool. \"\n",
" \"The RECOMMENDED format is JSON Schema.\"\n",
" )\n",
" )\n",
" response: Any = Field(\n",
" default=None,\n",
" description=(\n",
" \"Schema that defines the response returned by the tool. \"\n",
" \"The RECOMMENDED format is JSON Schema.\"\n",
" )\n",
" )\n",
"\n",
" class Config:\n",
" extra = \"allow\"\n",
"\n",
"class ToolDefinitions(RootModel[List[ToolDefinition]]):\n",
" \"\"\"\n",
" Represents the list of tool definitions available to the GenAI agent or model.\n",
" \"\"\"\n",
" pass\n",
"\n",
"# Print the JSON schema for the ToolDefinitions model\n",
"print(json.dumps(ToolDefinitions.model_json_schema(), indent=4))"
]
}
],
"metadata": {
Expand All @@ -240,7 +297,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.13.5"
"version": "3.13.7"
}
},
"nbformat": 4,
Expand Down
18 changes: 12 additions & 6 deletions docs/gen-ai/openai.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -200,13 +200,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.

---

Expand Down
Loading
Loading