Add JSON Schema Definition for gen_ai.tool.definitions

[Cirilla-zmh]

Fixes #2721 #1835

Changes

Add JSON schema definition for gen_ai.tool.definitions.

Important

Pull requests acceptance are subject to the triage process as described in Issue and PR Triage Management.
PRs that do not follow the guidance above, may be automatically rejected and closed.

Merge requirement checklist

• CONTRIBUTING.md guidelines followed.
• Change log entry added, according to the guidelines in When to add a changelog entry.
  • If your PR does not need a change log, start the PR title with [chore]
• Links to the prototypes or existing instrumentations (when adding or changing conventions)

[Cirilla-zmh]

This is the continued PR of #2793

[lmolkova]

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
    ]

[lmolkova]

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

[Cirilla-zmh]

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);

[alexmojaki]

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

[gyliu513]

+1 for a python script here.

[gyliu513]

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

[gyliu513]

+1 for a python script here.