fix: type AI SDK tool metadata fields

Author: omeraplak

packages/core/src/agent/agent.spec-d.ts

@@ -226,6 +226,8 @@ describe("Agent Type System", () => {
             inputSchema: z.object({ value: z.string() }),
             execute: async ({ value }) => ({ result: value }),
             voltagent: {
+              name: "test_tool",
+              purpose: "Exercise AI SDK tool metadata typing",
               tags: ["test"],
             },
           }),

packages/core/src/tool/ai-sdk-tool.ts

@@ -10,6 +10,17 @@ const VOLTAGENT_RAW_AI_SDK_TOOL_SYMBOL = Symbol.for("@voltagent/core.tool.raw-ai
 const metadataStore = new WeakMap<object, VoltAgentToolMetadata>();
 
 export type VoltAgentToolMetadata<INPUT = unknown, OUTPUT = unknown> = {
+  /**
+   * Optional VoltAgent-facing tool name for display or metadata consumers.
+   *
+   * When the tool is registered in an AI SDK ToolSet, the object key remains
+   * the execution name used by the model and tool calls.
+   */
+  name?: string;
+  /**
+   * Optional VoltAgent-facing purpose for display or metadata consumers.
+   */
+  purpose?: string;
   /**
    * Optional user-defined tags for organizing or routing tools.
    */

packages/core/src/tool/manager/index.spec.ts

@@ -315,6 +315,8 @@ describe("ToolManager", () => {
         inputSchema,
         execute,
         voltagent: {
+          name: "weatherLookup",
+          purpose: "Fetch weather observations",
           tags: ["weather"],
           needsApproval: true,
           hooks,
@@ -345,6 +347,8 @@ describe("ToolManager", () => {
         "get_weather",
         aiTool,
         expect.objectContaining({
+          name: "weatherLookup",
+          purpose: "Fetch weather observations",
           tags: ["weather"],
           needsApproval: true,
           hooks,

website/docs/agents/tools.md

@@ -58,6 +58,8 @@ const agent = new Agent({
         return { location, temperature: 22, conditions: "sunny" };
       },
       voltagent: {
+        name: "getWeather",
+        purpose: "Fetch current weather for a location",
         tags: ["weather", "external-api"],
         hooks: {
           onStart: ({ tool }) => {
@@ -77,6 +79,8 @@ Each AI SDK-style tool has:
 - **inputSchema**: Input schema defined with Zod
 - **execute**: Function that runs when the tool is called
 - **providerOptions** (optional): Provider-specific options for advanced features
+- **voltagent.name** (optional): VoltAgent-facing name for display or metadata consumers. The ToolSet key remains the execution name.
+- **voltagent.purpose** (optional): VoltAgent-facing purpose for display or metadata consumers.
 - **voltagent.tags** (optional): Optional user-defined tags for organizing or labeling tools.
 - **voltagent.hooks** (optional): VoltAgent lifecycle hooks for observing or post-processing tool execution.
 - **voltagent.needsApproval** (optional): Static approval metadata for existing VoltAgent approval or tool-policy flows. Prefer call-level `toolApproval` for new per-request approval flows.