Meta Tools provide dynamic tool discovery and execution capabilities for TypeScript/Node.js applications, allowing your AI agents to explore and use tools at runtime.

​
Overview

Meta Tools enable your TypeScript agents to:
  • Discover tools based on natural language queries
  • Execute tools dynamically without knowing their names in advance
  • Explore capabilities of connected integrations
  • Adapt behavior based on available tools
Main Concepts: For conceptual information about Meta Tools and how they work, see the Meta Tools Introduction. This page focuses on TypeScript-specific implementation details.

​
Getting Meta Tools

import { StackOneToolSet } from '@stackone/ai';

const toolset = new StackOneToolSet();
const tools = toolset.getStackOneTools('*', 'your-account-id');

// Get meta tools
const metaTools = await tools.metaTools();
Complete TypeScript Examples: View the full implementation with all TypeScript-specific patterns in our Meta Tools TypeScript Example.

​
Available Meta Tools

​
Search Tools

Find relevant tools based on natural language queries: 
const searchTool = metaTools.getTool('meta_search_tools');

const results = await searchTool.execute({
  query: 'employee management',
  limit: 5,
  minScore: 0.3
});

console.log('Found tools:', results.data.tools);
Parameters:
  • query (string): Natural language description of what you want to do
  • limit (number): Maximum number of tools to return (default: 10)
  • minScore (number): Minimum relevance score (0-1, default: 0.1)

​
Execute Tool

Execute any tool dynamically by name: 
const executeTool = metaTools.getTool('meta_execute_tool');

const result = await executeTool.execute({
  toolName: 'hris_list_employees',
  params: {
    limit: 10,
    department: 'engineering'
  }
});
Parameters:
  • toolName (string): Name of the tool to execute
  • params (object): Parameters to pass to the tool

​
Describe Tool

Get detailed information about a specific tool: 
const describeTool = metaTools.getTool('meta_describe_tool');

const description = await describeTool.execute({
  toolName: 'hris_list_employees'
});

console.log('Tool description:', description.data);

​
List Tools

Get a list of all available tools: 
const listTool = metaTools.getTool('meta_list_tools');

const allTools = await listTool.execute({
  category: 'hris',  // Optional: filter by category
  limit: 50
});

​
Framework Integration

​
OpenAI Functions

import { OpenAI } from 'openai';

const openai = new OpenAI();
const metaTools = await tools.metaTools();
const openAITools = metaTools.toOpenAI();

const completion = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [
    {
      role: 'user',
      content: 'Find tools for managing employee time off and show me recent requests'
    }
  ],
  tools: openAITools
});

// Handle tool calls
for (const toolCall of completion.choices[0].message.tool_calls || []) {
  const tool = metaTools.getTool(toolCall.function.name);
  const result = await tool.execute(JSON.parse(toolCall.function.arguments));
  console.log('Result:', result);
}
Complete OpenAI Example: See the full OpenAI integration with proper error handling and multi-turn conversations in openai-integration.ts.

​
Vercel AI SDK

import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

const metaTools = await tools.metaTools();
const aiSdkTools = metaTools.toAISDK();

const { text, toolCalls } = await generateText({
  model: openai('gpt-4'),
  tools: aiSdkTools,
  prompt: 'Search for HR tools and list employees in the engineering department',
  maxSteps: 5
});
Complete AI SDK Example: See the full Vercel AI SDK integration with streaming and tool execution in ai-sdk-integration.ts.

​
TypeScript-Specific Patterns

​
Type-Safe Tool Execution

TypeScript enables type-safe meta tool usage with proper interface definitions: 
interface ToolExecutionResult<T = any> {
  data: T;
  success: boolean;
  error?: string;
}

class TypedMetaToolsAgent {
  private metaTools: any;

  async executeWithTypes<T>(toolName: string, params: Record<string, unknown>): Promise<ToolExecutionResult<T>> {
    const executeTool = this.metaTools.getTool('meta_execute_tool');
    return await executeTool.execute({ toolName, params });
  }
}

​
Async/Await Patterns

Meta tools work seamlessly with modern TypeScript async patterns: 
async function discoverAndExecute(query: string) {
  const metaTools = await tools.metaTools();

  // Step 1: Search for tools
  console.log(`🔍 Searching for tools related to: "${query}"`);
  const searchTool = metaTools.getTool('meta_search_tools');
  const searchResults = await searchTool.execute({ query, limit: 5 });

  if (searchResults.data.tools.length === 0) {
    console.log('❌ No relevant tools found');
    return;
  }

  // Step 2: Execute the best tool
  const bestTool = searchResults.data.tools[0];
  console.log(`⚡ Executing: ${bestTool.name}`);

  const executeTool = metaTools.getTool('meta_execute_tool');
  const result = await executeTool.execute({
    toolName: bestTool.name,
    params: { limit: 5 }
  });

  console.log('✅ Result:', result.data);
}

​
Error Handling Patterns

async function safeToolExecution(toolName: string, params: any) {
  try {
    const executeTool = metaTools.getTool('meta_execute_tool');
    const result = await executeTool.execute({ toolName, params });
    return { success: true, data: result.data };
  } catch (error) {
    console.error(`Failed to execute ${toolName}:`, error);
    return { success: false, error: error.message };
  }
}
Complete TypeScript Examples: See comprehensive TypeScript implementation patterns including:

​
Best Practices

  1. Cache Tool Metadata: Store tool descriptions to avoid repeated API calls
  2. Handle Failures Gracefully: Meta tools may fail if integrations are unavailable
  3. Use Appropriate Filters: Set reasonable minScore and limit values
  4. Validate Parameters: Always validate parameters before executing tools
  5. Monitor Usage: Meta tools count toward your API usage limits

​
Limitations

  • Beta Status: API may change in future versions
  • Performance: Tool discovery adds latency compared to direct tool calls
  • Accuracy: Search results depend on tool metadata quality
  • Rate Limits: Subject to the same rate limits as regular tools

​
Next Steps