refactor(tools): rename meta tools to utility tools with tool_* prefix [ENG-11958] (#310)

* refactor(tools): rename meta tools to utility tools with tool_* prefix

Rename tool naming convention to avoid confusion with Facebook's Meta
brand. The "meta_*" prefix was ambiguous and could be misinterpreted.

File renames:
- examples/meta-tools.ts -> examples/utility-tools.ts

Tool name changes:
- meta_search_tools -> tool_search
- meta_execute_tool -> tool_execute
- meta_collect_tool_feedback -> tool_feedback

API changes:
- Tools.metaTools() -> Tools.utilityTools()

Internal type renames:
- MetaToolSearchResult -> ToolSearchResult

All tests pass (220 passed) and linting passes.

* Update src/tool.test.ts

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* fix(tests): update test descriptions from 'meta tools' to 'utility tools'

Address PR review comments to make test descriptions consistent with
the refactoring to use 'utility tools' terminology throughout:
- Update comment for mock tools creation function
- Fix 4 test descriptions that still referenced 'meta tools'

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: ryoppippi

README.md

@@ -355,18 +355,18 @@ This is especially useful when you want to:
 
 [View full example](examples/fetch-tools.ts)
 
-### Meta Tools (Beta)
+### Utility Tools (Beta)
 
-Meta tools enable dynamic tool discovery and execution, allowing AI agents to search for relevant tools based on natural language queries without hardcoding tool names.
+Utility tools enable dynamic tool discovery and execution, allowing AI agents to search for relevant tools based on natural language queries without hardcoding tool names.
 
-> **Beta Feature**: Meta tools are currently in beta and the API may change in future versions.
+> **Beta Feature**: Utility tools are currently in beta and the API may change in future versions.
 
-#### How Meta Tools Work
+#### How Utility Tools Work
 
-Meta tools provide two core capabilities:
+Utility tools provide two core capabilities:
 
-1. **Tool Discovery** (`meta_search_tools`): Search for tools using natural language queries
-2. **Tool Execution** (`meta_execute_tool`): Execute discovered tools dynamically
+1. **Tool Discovery** (`tool_search`): Search for tools using natural language queries
+2. **Tool Execution** (`tool_execute`): Execute discovered tools dynamically
 
 #### Basic Usage
 
@@ -378,14 +378,14 @@ const toolset = new StackOneToolSet({
 });
 const tools = await toolset.fetchTools();
 
-// Get meta tools for dynamic discovery
-const metaTools = await tools.metaTools();
+// Get utility tools for dynamic discovery
+const utilityTools = await tools.utilityTools();
 
 // Use with OpenAI
-const openAITools = metaTools.toOpenAI();
+const openAITools = utilityTools.toOpenAI();
 
 // Use with AI SDK
-const aiSdkTools = await metaTools.toAISDK();
+const aiSdkTools = await utilityTools.toAISDK();
 ```
 
 #### Example: Dynamic Tool Discovery with AI SDK
@@ -406,15 +406,15 @@ const { text } = await generateText({
 
 ```typescript
 // Step 1: Discover relevant tools
-const filterTool = metaTools.getTool('meta_search_tools');
+const filterTool = utilityTools.getTool('tool_search');
 const searchResult = await filterTool.execute({
 	query: 'employee time off vacation',
 	limit: 5,
 	minScore: 0.3, // Minimum relevance score (0-1)
 });
 
 // Step 2: Execute a discovered tool
-const executeTool = metaTools.getTool('meta_execute_tool');
+const executeTool = utilityTools.getTool('tool_execute');
 const result = await executeTool.execute({
 	toolName: 'bamboohr_create_time_off',
 	params: {
@@ -425,7 +425,7 @@ const result = await executeTool.execute({
 });
 ```
 
-[View full example](examples/meta-tools.ts)
+[View full example](examples/utility-tools.ts)
 
 ### Custom Base URL
 
@@ -473,7 +473,7 @@ The `dryRun` option returns an object containing:
 
 ### Feedback Collection Tool
 
-The StackOne AI SDK includes a built-in feedback collection tool (`meta_collect_tool_feedback`) that allows users to provide feedback on their experience with StackOne tools. This tool is automatically included when using `fetchTools()` and helps improve the SDK based on user input.
+The StackOne AI SDK includes a built-in feedback collection tool (`tool_feedback`) that allows users to provide feedback on their experience with StackOne tools. This tool is automatically included when using `fetchTools()` and helps improve the SDK based on user input.
 
 #### How It Works
 
@@ -498,7 +498,7 @@ const toolset = new StackOneToolSet({
 const tools = await toolset.fetchTools();
 
 // The feedback tool is automatically included
-const feedbackTool = tools.getTool('meta_collect_tool_feedback');
+const feedbackTool = tools.getTool('tool_feedback');
 
 // Use with AI agents - they will ask for user consent first
 const openAITools = tools.toOpenAI();
@@ -512,7 +512,7 @@ You can also use the feedback tool directly:
 
 ```typescript
 // Get the feedback tool
-const feedbackTool = tools.getTool('meta_collect_tool_feedback');
+const feedbackTool = tools.getTool('tool_feedback');
 
 // Submit feedback (after getting user consent)
 const result = await feedbackTool.execute({

examples/fetch-tools.test.ts

@@ -66,7 +66,7 @@ describe('fetch-tools example e2e', () => {
 		expect(toolsByProviders.length).toBeGreaterThan(0);
 		const providerToolNames = toolsByProviders.toArray().map((t) => t.name);
 		expect(
-			providerToolNames.every((name) => name.startsWith('bamboohr_') || name.startsWith('meta_')),
+			providerToolNames.every((name) => name.startsWith('bamboohr_') || name.startsWith('tool_')),
 		).toBe(true);
 
 		// Example 5: Filter by actions with exact match
@@ -85,7 +85,7 @@ describe('fetch-tools example e2e', () => {
 		});
 		const globToolNames = toolsByGlobPattern
 			.toArray()
-			.filter((t) => !t.name.startsWith('meta_'))
+			.filter((t) => !t.name.startsWith('tool_'))
 			.map((t) => t.name);
 		expect(globToolNames).toContain('bamboohr_list_employees');
 

examples/meta-tools.ts examples/utility-tools.tsexamples/meta-tools.ts renamed to examples/utility-tools.ts

@@ -1,9 +1,9 @@
 /**
- * This example demonstrates how to use meta tools for dynamic tool discovery and execution.
- * Meta tools allow AI agents to search for relevant tools based on natural language queries
+ * This example demonstrates how to use utility tools for dynamic tool discovery and execution.
+ * Utility tools allow AI agents to search for relevant tools based on natural language queries
  * and execute them dynamically without hardcoding tool names.
  *
- * @beta Meta tools are in beta and may change in future versions
+ * @beta Utility tools are in beta and may change in future versions
  */
 
 import process from 'node:process';
@@ -21,9 +21,9 @@ if (!apiKey) {
 const accountId = 'your-bamboohr-account-id';
 
 /**
- * Example 1: Using meta tools with AI SDK for dynamic tool discovery
+ * Example 1: Using utility tools with AI SDK for dynamic tool discovery
  */
-const metaToolsWithAISDK = async (): Promise<void> => {
+const utilityToolsWithAISDK = async (): Promise<void> => {
 	console.log('🔍 Example 1: Dynamic tool discovery with AI SDK\n');
 
 	// Initialize StackOne toolset
@@ -35,14 +35,14 @@ const metaToolsWithAISDK = async (): Promise<void> => {
 	// Fetch all available tools via MCP
 	const allTools = await toolset.fetchTools();
 
-	// Get meta tools for dynamic discovery and execution
-	const metaTools = await allTools.metaTools();
-	const aiSdkMetaTools = await metaTools.toAISDK();
+	// Get utility tools for dynamic discovery and execution
+	const utilityTools = await allTools.utilityTools();
+	const aiSdkUtilityTools = await utilityTools.toAISDK();
 
-	// Use meta tools to dynamically find and execute relevant tools
+	// Use utility tools to dynamically find and execute relevant tools
 	const { text, toolCalls } = await generateText({
 		model: openai('gpt-5.1'),
-		tools: aiSdkMetaTools,
+		tools: aiSdkUtilityTools,
 		prompt: `I need to create a time off request for an employee.
     First, find the right tool for this task, then use it to create a time off request
     for employee ID "emp_123" from January 15, 2024 to January 19, 2024.`,
@@ -54,9 +54,9 @@ const metaToolsWithAISDK = async (): Promise<void> => {
 };
 
 /**
- * Example 2: Using meta tools with OpenAI for HR assistant
+ * Example 2: Using utility tools with OpenAI for HR assistant
  */
-const metaToolsWithOpenAI = async (): Promise<void> => {
+const utilityToolsWithOpenAI = async (): Promise<void> => {
 	console.log('\n🤖 Example 2: HR Assistant with OpenAI\n');
 
 	const { OpenAI } = await import('openai');
@@ -75,9 +75,9 @@ const metaToolsWithOpenAI = async (): Promise<void> => {
 		actions: ['bamboohr_*'],
 	});
 
-	// Get meta tools
-	const metaTools = await bamboohrTools.metaTools();
-	const openAIMetaTools = metaTools.toOpenAI();
+	// Get utility tools
+	const utilityTools = await bamboohrTools.utilityTools();
+	const openAIUtilityTools = utilityTools.toOpenAI();
 
 	// Create an HR assistant that can discover and use tools dynamically
 	const response = await openaiClient.chat.completions.create({
@@ -86,16 +86,16 @@ const metaToolsWithOpenAI = async (): Promise<void> => {
 			{
 				role: 'system',
 				content: `You are an HR assistant with access to various HR tools.
-        Use the meta_search_tools to find appropriate tools for user requests,
-        then use meta_execute_tool to execute them.`,
+        Use the tool_search to find appropriate tools for user requests,
+        then use tool_execute to execute them.`,
 			},
 			{
 				role: 'user',
 				content:
 					'Can you help me find tools for managing employee records and then list current employees?',
 			},
 		],
-		tools: openAIMetaTools,
+		tools: openAIUtilityTools,
 		tool_choice: 'auto',
 	});
 
@@ -113,10 +113,10 @@ const metaToolsWithOpenAI = async (): Promise<void> => {
 };
 
 /**
- * Example 3: Direct usage of meta tools without AI
+ * Example 3: Direct usage of utility tools without AI
  */
-const directMetaToolUsage = async (): Promise<void> => {
-	console.log('\n🛠️  Example 3: Direct meta tool usage\n');
+const directUtilityToolUsage = async (): Promise<void> => {
+	console.log('\n🛠️  Example 3: Direct utility tool usage\n');
 
 	// Initialize toolset
 	const toolset = new StackOneToolSet({
@@ -128,12 +128,12 @@ const directMetaToolUsage = async (): Promise<void> => {
 	const allTools = await toolset.fetchTools();
 	console.log(`Total available tools: ${allTools.length}`);
 
-	// Get meta tools
-	const metaTools = await allTools.metaTools();
+	// Get utility tools
+	const utilityTools = await allTools.utilityTools();
 
 	// Step 1: Search for relevant tools
-	const filterTool = metaTools.getTool('meta_search_tools');
-	if (!filterTool) throw new Error('meta_search_tools not found');
+	const filterTool = utilityTools.getTool('tool_search');
+	if (!filterTool) throw new Error('tool_search not found');
 	const searchResult = await filterTool.execute({
 		query: 'employee management create update list',
 		limit: 5,
@@ -152,8 +152,8 @@ const directMetaToolUsage = async (): Promise<void> => {
 
 	// Step 2: Execute one of the found tools
 	if (foundTools.length > 0) {
-		const executeTool = metaTools.getTool('meta_execute_tool');
-		if (!executeTool) throw new Error('meta_execute_tool not found');
+		const executeTool = utilityTools.getTool('tool_execute');
+		if (!executeTool) throw new Error('tool_execute not found');
 		const firstTool = foundTools[0];
 
 		console.log(`\nExecuting ${firstTool.name}...`);
@@ -205,14 +205,14 @@ const dynamicToolRouter = async (): Promise<void> => {
 	// Combine tools
 	const combinedTools = new Tools([...bamboohrTools.toArray(), ...workdayTools.toArray()]);
 
-	// Get meta tools for the combined set
-	const metaTools = await combinedTools.metaTools();
+	// Get utility tools for the combined set
+	const utilityTools = await combinedTools.utilityTools();
 
 	// Create a router function that finds and executes tools based on intent
 	const routeAndExecute = async (intent: string, params: JsonObject = {}) => {
-		const filterTool = metaTools.getTool('meta_search_tools');
-		const executeTool = metaTools.getTool('meta_execute_tool');
-		if (!filterTool || !executeTool) throw new Error('Meta tools not found');
+		const filterTool = utilityTools.getTool('tool_search');
+		const executeTool = utilityTools.getTool('tool_execute');
+		if (!filterTool || !executeTool) throw new Error('Utility tools not found');
 
 		// Find relevant tools
 		const searchResult = await filterTool.execute({
@@ -258,14 +258,14 @@ const main = async () => {
 	try {
 		// Run examples based on environment setup
 		if (process.env.OPENAI_API_KEY) {
-			await metaToolsWithAISDK();
-			await metaToolsWithOpenAI();
+			await utilityToolsWithAISDK();
+			await utilityToolsWithOpenAI();
 		} else {
 			console.log('⚠️  OPENAI_API_KEY not found, skipping AI examples\n');
 		}
 
 		// These examples work without AI
-		await directMetaToolUsage();
+		await directUtilityToolUsage();
 		await dynamicToolRouter();
 	} catch (error) {
 		console.error('Error running examples:', error);
@@ -277,4 +277,4 @@ if (import.meta.main) {
 	await main();
 }
 
-export { metaToolsWithAISDK, metaToolsWithOpenAI, directMetaToolUsage, dynamicToolRouter };
+export { utilityToolsWithAISDK, utilityToolsWithOpenAI, directUtilityToolUsage, dynamicToolRouter };

src/feedback.test.ts

@@ -18,7 +18,7 @@ interface FeedbackResult {
 	results: FeedbackResultItem[];
 }
 
-describe('meta_collect_tool_feedback', () => {
+describe('tool_feedback', () => {
 	describe('validation tests', () => {
 		it('test_missing_required_fields', async () => {
 			const tool = createFeedbackTool();
@@ -274,7 +274,7 @@ describe('meta_collect_tool_feedback', () => {
 		it('test_tool_integration', async () => {
 			// Test tool properties
 			const tool = createFeedbackTool();
-			expect(tool.name).toBe('meta_collect_tool_feedback');
+			expect(tool.name).toBe('tool_feedback');
 			expect(tool.description).toContain('Collects user feedback');
 			expect(tool.parameters).toBeDefined();
 
@@ -283,7 +283,7 @@ describe('meta_collect_tool_feedback', () => {
 			expect(openaiFormat).toMatchObject({
 				type: 'function',
 				function: {
-					name: 'meta_collect_tool_feedback',
+					name: 'tool_feedback',
 					description: expect.stringContaining('Collects user feedback'),
 					parameters: expect.objectContaining({
 						type: 'object',

src/feedback.ts

@@ -47,7 +47,7 @@ export function createFeedbackTool(
 		accountId,
 		baseUrl,
 	};
-	const name = 'meta_collect_tool_feedback' as const;
+	const name = 'tool_feedback' as const;
 	const description =
 		'Collects user feedback on StackOne tool performance. First ask the user, "Are you ok with sending feedback to StackOne?" and mention that the LLM will take care of sending it. Call this tool only when the user explicitly answers yes.';
 	const parameters = {