​
Initialize the ToolSet

Start by creating a StackOneToolSet instance: 
import { StackOneToolSet } from '@stackone/ai';

// Initialize the toolset
const toolset = new StackOneToolSet();
const accountId = 'your-customer-account-id';

​
Get Tools

Use glob patterns to retrieve specific tools: 
// Get all HRIS tools
const hrisTools = toolset.getStackOneTools('hris_*', accountId);

// Get all ATS tools
const atsTools = toolset.getStackOneTools('ats_*', accountId);

// Get specific list operations
const listTools = toolset.getStackOneTools('hris_list_*', accountId);

​
Execute Tools

​
Basic Tool Execution

// Get a specific tool
const employeeTool = tools.getTool('hris_list_employees');

// Execute with parameters
const employees = await employeeTool.execute({ 
  limit: 10,
  include_details: true 
});

console.log(employees);

​
Tool Execution with Error Handling

import { StackOneError, ToolExecutionError } from '@stackone/ai';

try {
  const result = await employeeTool.execute({ id: 'employee-123' });
  console.log('Success:', result);
} catch (error) {
  if (error instanceof ToolExecutionError) {
    console.error('Tool execution failed:', error.message);
  } else if (error instanceof StackOneError) {
    console.error('StackOne API error:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

​
Tool Filtering

​
Advanced Filtering Patterns

// Get all tools for multiple categories
const allTools = toolset.getStackOneTools(['hris_*', 'ats_*'], accountId);

// Exclude dangerous operations
const safeTools = toolset.getStackOneTools(['hris_*', '!hris_delete_*'], accountId);

// Get only read operations
const readOnlyTools = toolset.getStackOneTools(['*_list_*', '*_get_*'], accountId);

​
List Available Tools

// Get all available tools
const tools = toolset.getStackOneTools('*', accountId);

// List tool names
const toolNames = tools.listTools();
console.log('Available tools:', toolNames);

// Get specific tool information
const toolInfo = tools.getToolInfo('hris_list_employees');
console.log('Tool info:', toolInfo);

​
Working with Results

​
Processing Tool Results

const employees = await employeeTool.execute({ limit: 50 });

// Process the results
employees.data.forEach(employee => {
  console.log(`${employee.first_name} ${employee.last_name} - ${employee.email}`);
});

// Check pagination
if (employees.next) {
  console.log('More results available');
}

​
Handling Different Data Types

// List operations return arrays
const departments = await deptTool.execute();
console.log(`Found ${departments.data.length} departments`);

// Get operations return single objects
const employee = await employeeTool.execute({ id: 'emp_123' });
console.log(`Employee: ${employee.data.display_name}`);

​
Multi-Tool Operations

​
Sequential Execution

// Execute tools in sequence
const departments = await toolset.getStackOneTools('hris_list_departments', accountId)
  .getTool('hris_list_departments')
  .execute();

const employees = await toolset.getStackOneTools('hris_list_employees', accountId)
  .getTool('hris_list_employees')  
  .execute({ department_id: departments.data[0].id });

​
Parallel Execution

// Execute multiple tools simultaneously
const [employees, departments, locations] = await Promise.all([
  toolset.getStackOneTools('hris_list_employees', accountId)
    .getTool('hris_list_employees').execute(),
  toolset.getStackOneTools('hris_list_departments', accountId) 
    .getTool('hris_list_departments').execute(),
  toolset.getStackOneTools('hris_list_locations', accountId)
    .getTool('hris_list_locations').execute()
]);

​
Environment Configuration

​
Using Environment Variables

// Set in your .env file
// STACKONE_API_KEY=your_api_key
// STACKONE_ACCOUNT_ID=your_account_id

const toolset = new StackOneToolSet({
  apiKey: process.env.STACKONE_API_KEY,
  // accountId can still be passed per operation
});

// Use environment account ID as default
const accountId = process.env.STACKONE_ACCOUNT_ID || 'fallback-account-id';

​
Dynamic Account Handling

// Handle multiple customer accounts
const customerAccounts = ['account-1', 'account-2', 'account-3'];

for (const accountId of customerAccounts) {
  const tools = toolset.getStackOneTools('hris_list_employees', accountId);
  const employees = await tools.getTool('hris_list_employees').execute();
  
  console.log(`Account ${accountId}: ${employees.data.length} employees`);
}

​
Next Steps