feat(core): add tool metadata (#8644)

Author: hntrl

langchain-core/src/messages/tool.ts

@@ -31,6 +31,7 @@ export interface ToolMessageFieldsWithToolCallId extends ToolMessageFields {
    * @version 0.2.19
    */
   status?: "success" | "error";
+  metadata?: Record<string, unknown>;
 }
 
 /**
@@ -78,6 +79,8 @@ export class ToolMessage extends BaseMessage implements DirectToolOutput {
 
   tool_call_id: string;
 
+  metadata?: Record<string, unknown>;
+
   /**
    * Artifact of the Tool execution which is not meant to be sent to the model.
    *
@@ -109,6 +112,7 @@ export class ToolMessage extends BaseMessage implements DirectToolOutput {
     this.tool_call_id = fields.tool_call_id;
     this.artifact = fields.artifact;
     this.status = fields.status;
+    this.metadata = fields.metadata;
   }
 
   _getType(): MessageType {

langchain-core/src/tools/index.ts

@@ -36,6 +36,7 @@ import {
   type ZodStringV4,
   type ZodObjectV3,
   type ZodObjectV4,
+  getSchemaDescription,
 } from "../utils/types/zod.js";
 import type {
   StructuredToolCallInput,
@@ -137,6 +138,7 @@ export abstract class StructuredTool<
       fields?.verboseParsingErrors ?? this.verboseParsingErrors;
     this.responseFormat = fields?.responseFormat ?? this.responseFormat;
     this.defaultConfig = fields?.defaultConfig ?? this.defaultConfig;
+    this.metadata = fields?.metadata ?? this.metadata;
   }
 
   protected abstract _call(
@@ -247,7 +249,7 @@ export abstract class StructuredTool<
       parsed = inputForValidation as SchemaOutputT;
     }
 
-    const config = parseCallbackConfigArg(configArg);
+    const config = parseCallbackConfigArg(configArg) as ToolRunnableConfig;
     const callbackManager_ = CallbackManager.configure(
       config.callbacks,
       this.callbacks,
@@ -307,6 +309,7 @@ export abstract class StructuredTool<
       artifact,
       toolCallId,
       name: this.name,
+      metadata: this.metadata,
     });
     await runManager?.handleToolEnd(formattedOutput);
     return formattedOutput as ToolReturnType<TArg, TConfig, ToolOutputT>;
@@ -638,7 +641,7 @@ export function tool<
       ...fields,
       description:
         fields.description ??
-        (fields.schema as { description?: string } | undefined)?.description ??
+        (fields.schema && getSchemaDescription(fields.schema)) ??
         `${fields.name} tool`,
       func: async (input, runManager, config) => {
         return new Promise<ToolOutputT>((resolve, reject) => {
@@ -708,8 +711,9 @@ function _formatToolOutput<TOutput extends ToolOutputType>(params: {
   name: string;
   artifact?: unknown;
   toolCallId?: string;
+  metadata?: Record<string, unknown>;
 }): ToolMessage | TOutput {
-  const { content, artifact, toolCallId } = params;
+  const { content, artifact, toolCallId, metadata } = params;
   if (toolCallId && !isDirectToolOutput(content)) {
     if (
       typeof content === "string" ||
@@ -721,13 +725,15 @@ function _formatToolOutput<TOutput extends ToolOutputType>(params: {
         artifact,
         tool_call_id: toolCallId,
         name: params.name,
+        metadata,
       });
     } else {
       return new ToolMessage({
         content: _stringify(content),
         artifact,
         tool_call_id: toolCallId,
         name: params.name,
+        metadata,
       });
     }
   } else {

langchain-core/src/tools/tests/tools.test.ts

@@ -4,12 +4,13 @@ import { z as z4 } from "zod/v4";
 
 import {
   DynamicStructuredTool,
+  DynamicTool,
   StructuredToolParams,
   ToolInputParsingException,
   isStructuredToolParams,
   tool,
 } from "../index.js";
-import { ToolMessage } from "../../messages/tool.js";
+import { ToolCall, ToolMessage } from "../../messages/tool.js";
 import { RunnableConfig } from "../../runnables/types.js";
 
 test("Tool should error if responseFormat is content_and_artifact but the function doesn't return a tuple", async () => {
@@ -447,3 +448,30 @@ describe("isStructuredToolParams", () => {
     expect(isStructuredToolParams(nonStructuredToolParams)).toBe(false);
   });
 });
+
+describe("DynamicTool", () => {
+  test("will thread metadata through to a resulting ToolMessage", async () => {
+    const tool = new DynamicTool({
+      name: "test",
+      description: "test",
+      metadata: {
+        foo: "bar",
+      },
+      func: async () => "test",
+    });
+
+    const input: ToolCall = {
+      id: "test_id",
+      name: "test",
+      args: { input: "test" },
+      type: "tool_call",
+    };
+
+    const result = await tool.invoke(input);
+
+    expect(result).toBeInstanceOf(ToolMessage);
+    expect(result.metadata).toEqual({
+      foo: "bar",
+    });
+  });
+});

langchain-core/src/tools/types.ts

@@ -81,12 +81,18 @@ export interface ToolParams extends BaseLangChainParams {
    * @default false
    */
   verboseParsingErrors?: boolean;
+  /**
+   * Metadata for the tool.
+   */
+  metadata?: Record<string, unknown>;
 }
 
 export type ToolRunnableConfig<
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   ConfigurableFieldType extends Record<string, any> = Record<string, any>
-> = RunnableConfig<ConfigurableFieldType> & { toolCall?: ToolCall };
+> = RunnableConfig<ConfigurableFieldType> & {
+  toolCall?: ToolCall;
+};
 
 /**
  * Schema for defining tools.