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 5 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 all commits
Commits
Show all changes
5 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
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.
#
# 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
Copy link
Member Author

@Cirilla-zmh Cirilla-zmh Oct 21, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Whether we need to capture 'name' & 'type' by default, considering they are important informations and have no sensitive/huge content? cc @ShipraJain01 @lmolkova

Here is a prototype from spring-ai instrumentation:

options.getToolCallbacks().stream()
    .map(
        toolCallback -> {
          String name = toolCallback.getToolDefinition().name();
          String type = "function";
          if (messageCaptureOptions.captureMessageContent()) {
            return ToolDefinition.create(
                type, name, toolCallback.getToolDefinition().description(), toolCallback.getToolDefinition().getArguments());
          } else {
            return ToolDefinition.create(type, name, null, null);
          }
        })
    .filter(Objects::nonNull)
    .forEach(toolDefinitions::append);

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
Copy link
Contributor

@alexmojaki alexmojaki Oct 21, 2025

Choose a reason for hiding this comment

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

@lmolkova I feel like this should just be a python script with comments and docstrings, reviewing this notebook format in github is annoying

Copy link
Member

@gyliu513 gyliu513 Oct 28, 2025

Choose a reason for hiding this comment

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

+1 for a python script here.

Copy link
Member

@gyliu513 gyliu513 Oct 28, 2025

Choose a reason for hiding this comment

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

maybe a markdown file also works here, embedding the code in the markdown file and and also with the output .

python code
this is the output of above code

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",
Copy link
Member

@lmolkova lmolkova Oct 20, 2025

Choose a reason for hiding this comment

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

bringing @alexmojaki 's comment here https://github.com/open-telemetry/semantic-conventions/pull/2793/files#r2369871417

Custom tools are only supported by OpenAI Chat API and are not even available in the Responses API - https://platform.openai.com/docs/api-reference/responses/create#responses-create-tools

  1. I'd suggest to remove this enum member
  2. The ToolDefinition below only works for functions and should only be used when ToolType is function.
  3. We need to leave a room to support non-function tool definitions (e.g. file search) and their parameters. I.e. we'd need something like 
     ToolDefinition = Union[
     FunctionDefinition,
     GenericToolDefinition,  # Catch-all for any other type
     # Add other tool definition types here as needed,
     # e.g. file search, code interpreter, etc
 ]

"\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",
Copy link
Member

@lmolkova lmolkova Oct 20, 2025

Choose a reason for hiding this comment

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

see comment above - parameters and response are specific to functions and don't necessarily work for non-function tools (e.g. file search)

" 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