feat(a365): add typed ExecuteTool schemas

A365_DOCUMENTATION.md

@@ -17,10 +17,15 @@ Use scopes when you want explicit spans for agent, tool, inference, or output wo
 
 ```typescript
 import {
+  ExecuteToolCallArguments,
+  ExecuteToolCallResult,
   ExecuteToolScope,
   InferenceOperationType,
   InferenceScope,
   InvokeAgentScope,
+  ToolCallAction,
+  ToolCallOutcomeStatus,
+  ToolPolicyDecision,
 } from "@microsoft/opentelemetry";
 
 const invokeScope = InvokeAgentScope.start(
@@ -36,9 +41,36 @@ const invokeScope = InvokeAgentScope.start(
 );
 
 invokeScope.run(async () => {
+  const toolArguments = new ExecuteToolCallArguments({
+    action: ToolCallAction.READ,
+    resources: [
+      {
+        id: "drive-item-1",
+        uri: "https://contoso.example/items/1",
+        name: "Quarterly plan",
+        type: "document",
+        provider: "sharepoint",
+        identifiers: [{ type: "driveItem", value: "1" }],
+        container: {
+          id: "folder-1",
+          uri: "https://contoso.example/folders/1",
+          type: "folder",
+        },
+        extension_data: { custom_resource_field: "kept" },
+      },
+    ],
+    parameters: { query: "hello", includeArchived: false },
+    extension_data: { custom_argument_field: "kept" },
+  });
+
   const toolScope = ExecuteToolScope.start(
     { conversationId: "conv-123", sessionId: "session-456" },
-    { toolName: "Search", input: { query: "hello" } },
+    {
+      toolName: "Search",
+      arguments: toolArguments,
+      toolCallId: "tool-call-123",
+      toolType: "function",
+    },
     { agentId: "agent-1", tenantId: "tenant-1" },
   );
 
@@ -48,6 +80,36 @@ invokeScope.run(async () => {
     { agentId: "agent-1", tenantId: "tenant-1" },
   );
 
+  toolScope.recordResponse(
+    new ExecuteToolCallResult({
+      outcome: {
+        status: ToolCallOutcomeStatus.SUCCESS,
+        code: "200",
+        message: "Completed",
+      },
+      resources: [
+        {
+          id: "drive-item-1",
+          name: "Quarterly plan",
+          type: "document",
+          outcome: {
+            status: ToolCallOutcomeStatus.SUCCESS,
+            code: "200",
+          },
+          policy: {
+            decision: ToolPolicyDecision.ALLOW,
+            id: "policy-1",
+            name: "AllowDocumentRead",
+          },
+          data: { snippetCount: 3 },
+          extension_data: { custom_result_field: "kept" },
+        },
+      ],
+      pagination: { has_more: false, total_count: 1 },
+      extension_data: { custom_result_field: "kept" },
+    }),
+  );
+
   toolScope.dispose();
   inferenceScope.dispose();
 });
@@ -62,6 +124,16 @@ invokeScope.recordResponseParameters({
 invokeScope.dispose();
 ```
 
+`ExecuteToolScope` serializes arguments to `gen_ai.tool.call.arguments` and results to
+`gen_ai.tool.call.result` as JSON span attributes, so they may contain sensitive data.
+Use `extension_data` for provider-specific fields on any typed ExecuteTool model. Non-empty
+extension data is emitted under the model's `metadata` JSON property. Metadata keys remain
+isolated from declared schema fields, so an `extension_data.action` or
+`extension_data.schema_version` value cannot replace the typed `action` or `schema_version`.
+Typed payloads that contain invalid enum tokens, non-finite numbers, unsupported values, or
+reference cycles are replaced with
+`{"serialization_error":"Failed to serialize execute tool payload."}`.
+
 `InvokeAgentScope`, `InferenceScope`, and `ExecuteToolScope` accept `request.sessionId`.
 When you provide it, those scopes write `microsoft.session.id` directly on the created
 span instead of relying on later baggage enrichment. `OutputScope` does not currently
@@ -90,9 +162,9 @@ captures response and usage values after the agent completes.
 | `responseParameters.cacheWriteInputTokens` | `gen_ai.usage.cache_write.input_tokens`                    |
 | `responseParameters.cacheReadInputTokens`  | `gen_ai.usage.cache_read.input_tokens`                     |
 | `agentDetails.providerName`                | `gen_ai.provider.name`                                     |
-
 System instructions may contain sensitive content. Only capture them when you
 intend to store prompt text and have reviewed downstream access controls.
+intend to store prompt text and have reviewed downstream access controls.
 
 ## Baggage And Context
 

CHANGELOG.md

@@ -6,6 +6,7 @@
 - Default `InvokeAgentScope` spans to `SpanKind.INTERNAL` while preserving explicit span-kind overrides. [#241](https://github.com/microsoft/opentelemetry-distro-javascript/pull/241)
 
 ### Features Added
+- Add typed ExecuteTool argument and result schemas with default schema_version: "1.0", collision-safe `extension_data` emitted under `metadata`, and non-throwing validation aligned with the .NET and Python distros. [#240](https://github.com/microsoft/opentelemetry-distro-javascript/pull/240)
 - Add manual `sessionId` propagation to `ExecuteToolScope` and `InferenceScope`, plus opt-in custom baggage enrichment for recognized GenAI spans through `BaggageBuilder.customAttribute()` and `customAttributes()`. [#242](https://github.com/microsoft/opentelemetry-distro-javascript/pull/242)
 - Add GenAI v1.42 InvokeAgent request, response, cache-token, and provider attribute capture for manual A365 scopes. [#239](https://github.com/microsoft/opentelemetry-distro-javascript/pull/239)
 

src/a365/contracts.ts

@@ -9,6 +9,27 @@
  */
 
 import type { SpanKind, TimeInput, Link, Context, TraceState } from "@opentelemetry/api";
+import type { ExecuteToolCallArguments } from "./tool-call-models.js";
+
+export {
+  ToolCallAction,
+  ToolCallOutcomeStatus,
+  ToolPolicyDecision,
+  ExecuteToolCallArguments,
+  ExecuteToolCallResult,
+} from "./tool-call-models.js";
+export type {
+  ToolCallExtensionData,
+  ToolCallIdentifier,
+  ToolCallContainer,
+  ToolCallResource,
+  ToolCallResultOutcome,
+  ToolCallResultSensitivity,
+  ToolCallResultPolicy,
+  ToolCallResultSecurity,
+  ToolCallResultPagination,
+  ToolCallResultResource,
+} from "./tool-call-models.js";
 
 // ---------------------------------------------------------------------------
 // Default finish reason (per OTel spec)
@@ -422,8 +443,8 @@ export interface InvokeAgentScopeDetails {
 export interface ToolCallDetails {
   /** Name of the tool being called (required). */
   toolName: string;
-  /** Arguments passed to the tool, as an object or serialized string. */
-  arguments?: Record<string, unknown> | string;
+  /** Arguments passed to the tool, as an object, execute-tool schema model, or serialized string. */
+  arguments?: Record<string, unknown> | ExecuteToolCallArguments | string;
   /** Unique identifier of the tool call. */
   toolCallId?: string;
   /** Human-readable description of the tool. */

src/a365/index.ts

@@ -38,6 +38,11 @@ export {
   InvocationRole,
   InferenceOperationType,
   DEFAULT_FINISH_REASON,
+  ToolCallAction,
+  ToolCallOutcomeStatus,
+  ToolPolicyDecision,
+  ExecuteToolCallArguments,
+  ExecuteToolCallResult,
   GuardrailDecisionType,
   GuardrailRiskSeverity,
   GuardrailTargetType,
@@ -56,6 +61,16 @@ export type {
   ToolCallRequestPart,
   ToolCallResponsePart,
   ReasoningPart,
+  ToolCallExtensionData,
+  ToolCallIdentifier,
+  ToolCallContainer,
+  ToolCallResource,
+  ToolCallResultOutcome,
+  ToolCallResultSensitivity,
+  ToolCallResultPolicy,
+  ToolCallResultSecurity,
+  ToolCallResultPagination,
+  ToolCallResultResource,
   AgentDetails,
   UserDetails,
   CallerDetails,