7 min
technology
February 8, 2026

Tool Use and Integration

title: "Tool Use and Integration" description: "Research on tool discovery, execution, and result interpretation in agentic systems" date: 2026-02-06 topics: [tools, integration, execution, apis] sources: 0 status: initial

Tool Use and Integration

Overview

Tools extend agent capabilities beyond language generation, enabling interaction with external systems, code execution, and real-world actions. This research covers tool discovery, execution patterns, and result interpretation.

Tool Categories

1. System Tools

File System Operations

typescript
interface FileSystemTools {
  readFile(path: string): Promise<string>;
  writeFile(path: string, content: string): Promise<void>;
  listDirectory(path: string): Promise<FileInfo[]>;
  searchFiles(pattern: string): Promise<Match[]>;
}

Process Execution

typescript
interface ProcessTools {
  execute(command: string, options: ExecOptions): Promise<ExecResult>;
  spawn(command: string, args: string[]): ChildProcess;
  kill(pid: number, signal?: string): Promise<void>;
}

Network Operations

typescript
interface NetworkTools {
  fetch(url: string, options?: RequestInit): Promise<Response>;
  download(url: string, destination: string): Promise<void>;
  upload(source: string, url: string): Promise<void>;
}

2. Development Tools

Code Analysis

typescript
interface CodeAnalysisTools {
  parseCode(source: string, language: string): AST;
  analyzeDependencies(projectPath: string): DependencyGraph;
  findReferences(symbol: string, codebase: Codebase): Location[];
  calculateComplexity(code: string): ComplexityMetrics;
}

Build and Test

typescript
interface BuildTools {
  compile(project: Project): Promise<BuildResult>;
  test(project: Project, filter?: string): Promise<TestResult>;
  lint(project: Project): Promise<LintResult>;
  format(project: Project): Promise<FormatResult>;
}

Version Control

typescript
interface VersionControlTools {
  git: {
    clone(url: string, path: string): Promise<void>;
    commit(message: string, files: string[]): Promise<void>;
    push(remote?: string, branch?: string): Promise<void>;
    diff(from: string, to: string): Promise<Diff>;
    log(options?: LogOptions): Promise<Commit[]>;
  };
}

3. External Service Tools

Database Operations

typescript
interface DatabaseTools {
  query(connection: Connection, sql: string): Promise<QueryResult>;
  migrate(connection: Connection, migrations: Migration[]): Promise<void>;
  backup(connection: Connection, destination: string): Promise<void>;
}

Cloud Services

typescript
interface CloudTools {
  deploy(service: string, config: DeployConfig): Promise<DeployResult>;
  provision(resources: Resource[]): Promise<ProvisionResult>;
  monitor(service: string): Promise<Metrics>;
  scale(service: string, replicas: number): Promise<void>;
}

Communication

typescript
interface CommunicationTools {
  sendMessage(channel: string, message: string): Promise<void>;
  createIssue(project: string, issue: Issue): Promise<Issue>;
  notify(user: User, notification: Notification): Promise<void>;
}

Tool Discovery

1. Static Tool Registry

typescript
interface ToolRegistry {
  tools: Map<ToolId, ToolDefinition>;
  
  register(tool: ToolDefinition): void {
    this.tools.set(tool.id, tool);
  }
  
  find(query: string): ToolDefinition[] {
    return Array.from(this.tools.values())
      .filter(t => this.matches(t, query));
  }
  
  get(id: ToolId): ToolDefinition {
    return this.tools.get(id);
  }
}

interface ToolDefinition {
  id: string;
  name: string;
  description: string;
  parameters: ParameterSchema;
  returns: ReturnSchema;
  examples: Example[];
  constraints: Constraint[];
}

2. Dynamic Tool Discovery

typescript
interface DynamicToolDiscovery {
  async discoverTools(context: Context): Promise<Tool[]> {
    // Scan available executables
    const executables = await this.scanPath();
    
    // Query APIs for available endpoints
    const apiEndpoints = await this.discoverAPIs(context);
    
    // Check environment for installed tools
    const installed = await this.checkInstalledTools();
    
    // Generate tool definitions
    return Promise.all([
      ...executables.map(e => this.generateToolFromExecutable(e)),
      ...apiEndpoints.map(a => this.generateToolFromAPI(a)),
      ...installed.map(i => this.generateToolFromInstalled(i))
    ]);
  }
}

3. Tool Selection

typescript
interface ToolSelector {
  async selectTool(
    task: Task,
    availableTools: Tool[]
  ): Promise<ToolSelection> {
    // Score each tool by relevance
    const scored = await Promise.all(
      availableTools.map(async tool => ({
        tool,
        score: await this.scoreRelevance(tool, task)
      }))
    );
    
    // Sort by score
    scored.sort((a, b) => b.score - a.score);
    
    // Return top match if confident
    if (scored[0].score > CONFIDENCE_THRESHOLD) {
      return {
        tool: scored[0].tool,
        confidence: scored[0].score,
        alternatives: scored.slice(1, 3)
      };
    }
    
    // Otherwise, ask for clarification
    return { clarificationNeeded: true };
  }
}

Tool Execution

1. Execution Patterns

Synchronous Execution

typescript
interface SyncExecution {
  async execute(tool: Tool, params: Params): Promise<Result> {
    // Validate parameters
    const validated = await this.validate(params, tool.schema);
    
    // Execute
    const result = await tool.execute(validated);
    
    // Validate output
    return this.validateOutput(result, tool.returnSchema);
  }
}

Asynchronous Execution

typescript
interface AsyncExecution {
  async executeLongRunning(
    tool: Tool,
    params: Params
  ): Promise<AsyncResult> {
    // Start execution
    const jobId = await tool.start(params);
    
    // Return handle for monitoring
    return {
      jobId,
      status: 'running',
      
      // Polling interface
      checkStatus: () => tool.getStatus(jobId),
      
      // Wait for completion
      waitForCompletion: async () => {
        while (true) {
          const status = await tool.getStatus(jobId);
          if (status.completed) return status.result;
          if (status.failed) throw new Error(status.error);
          await this.delay(1000);
        }
      },
      
      // Cancellation
      cancel: () => tool.cancel(jobId)
    };
  }
}

Streaming Execution

typescript
interface StreamingExecution {
  async executeWithStream(
    tool: Tool,
    params: Params
  ): Promise<ReadableStream> {
    const stream = await tool.executeStream(params);
    
    // Process stream chunks
    const processor = new TransformStream({
      transform(chunk, controller) {
        // Parse and enrich chunks
        const enriched = this.enrichChunk(chunk);
        controller.enqueue(enriched);
      }
    });
    
    return stream.pipeThrough(processor);
  }
}

2. Error Handling

typescript
interface ToolErrorHandler {
  async handleToolError(
    error: ToolError,
    context: ExecutionContext
  ): Promise<RecoveryAction> {
    // Classify error
    const classification = this.classifyError(error);
    
    switch (classification.type) {
      case 'timeout':
        return { action: 'retry', delay: this.calculateBackoff(context) };
        
      case 'rate_limit':
        return { 
          action: 'retry', 
          delay: error.retryAfter || 60000 
        };
        
      case 'invalid_input':
        return { 
          action: 'fix_params', 
          correction: await this.suggestFix(error, context) 
        };
        
      case 'permission_denied':
        return { 
          action: 'escalate', 
          message: 'Need elevated permissions' 
        };
        
      case 'resource_unavailable':
        return { action: 'fail', message: error.message };
        
      default:
        return { action: 'retry', delay: 5000, maxRetries: 3 };
    }
  }
}

3. Result Interpretation

typescript
interface ResultInterpreter {
  async interpretResult(
    result: ToolResult,
    context: ExecutionContext
  ): Promise<Interpretation> {
    // Parse structured output
    const structured = this.parseOutput(result);
    
    // Extract key information
    const keyPoints = this.extractKeyPoints(structured);
    
    // Determine success/failure
    const success = this.assessSuccess(structured, context);
    
    // Identify next actions
    const nextActions = this.suggestNextActions(structured, context);
    
    return {
      success,
      summary: this.summarize(structured),
      keyPoints,
      nextActions,
      raw: result
    };
  }
}

Tool Composition

1. Sequential Composition

typescript
interface SequentialComposition {
  async executeSequence(
    steps: ToolStep[]
  ): Promise<SequenceResult> {
    const results = [];
    let context = {};
    
    for (const step of steps) {
      // Substitute variables from context
      const params = this.substitute(step.params, context);
      
      // Execute
      const result = await this.execute(step.tool, params);
      
      // Store result
      results.push(result);
      context[step.outputKey] = result;
      
      // Check for failure
      if (!result.success && !step.continueOnError) {
        break;
      }
    }
    
    return { results, context };
  }
}

2. Parallel Composition

typescript
interface ParallelComposition {
  async executeParallel(
    branches: ToolBranch[]
  ): Promise<ParallelResult> {
    // Execute all branches concurrently
    const promises = branches.map(async branch => ({
      key: branch.key,
      result: await this.execute(branch.tool, branch.params)
    }));
    
    // Wait for all to complete
    const results = await Promise.all(promises);
    
    // Combine results
    return results.reduce((acc, { key, result }) => {
      acc[key] = result;
      return acc;
    }, {});
  }
}

3. Conditional Composition

typescript
interface ConditionalComposition {
  async executeConditional(
    condition: Condition,
    ifTrue: ToolStep[],
    ifFalse: ToolStep[]
  ): Promise<SequenceResult> {
    const evaluated = await this.evaluateCondition(condition);
    
    if (evaluated) {
      return this.executeSequence(ifTrue);
    } else {
      return this.executeSequence(ifFalse);
    }
  }
}

Tool Safety

1. Sandboxing

typescript
interface SandboxConfig {
  // Resource limits
  maxMemory: number;
  maxCpu: number;
  maxDisk: number;
  maxTime: number;
  
  // Network restrictions
  allowNetwork: boolean;
  allowedHosts: string[];
  
  // File system restrictions
  readOnlyPaths: string[];
  writablePaths: string[];
  forbiddenPaths: string[];
}

async function executeInSandbox(
  tool: Tool,
  params: Params,
  config: SandboxConfig
): Promise<Result> {
  const sandbox = await createSandbox(config);
  
  try {
    return await sandbox.run(() => tool.execute(params));
  } finally {
    await sandbox.destroy();
  }
}

2. Permission System

typescript
interface PermissionSystem {
  permissions: Map<ToolId, Permission[]>;
  
  checkPermission(
    tool: ToolId,
    action: Action,
    context: Context
  ): boolean {
    const toolPerms = this.permissions.get(tool);
    
    // Check if action is allowed
    return toolPerms?.some(p => 
      p.action === action && 
      p.condition(context)
    ) ?? false;
  }
  
  async requestPermission(
    tool: ToolId,
    action: Action
  ): Promise<Grant> {
    // Escalate to human if needed
    return await this.escalate({ tool, action });
  }
}

3. Audit Logging

typescript
interface ToolAudit {
  async logToolUse(
    tool: ToolId,
    params: Params,
    result: Result,
    context: ExecutionContext
  ): Promise<void> {
    await this.auditLog.write({
      timestamp: new Date(),
      tool,
      params: this.sanitizeForLog(params),
      result: this.sanitizeForLog(result),
      user: context.user,
      session: context.sessionId,
      success: result.success
    });
  }
}

Tool Development

1. Tool Definition Format

typescript
interface ToolSchema {
  name: string;
  description: string;
  version: string;
  
  parameters: {
    type: 'object';
    properties: Record<string, ParameterDef>;
    required: string[];
  };
  
  returns: {
    type: 'object';
    properties: Record<string, ReturnDef>;
  };
  
  examples: Example[];
  
  errorCodes: Record<string, string>;
  
  rateLimits?: {
    requestsPerMinute: number;
    requestsPerHour: number;
  };
}

2. Tool Testing

typescript
interface ToolTestSuite {
  tests: {
    name: string;
    input: Params;
    expectedOutput?: Result;
    expectedError?: string;
    setup?: () => Promise<void>;
    teardown?: () => Promise<void>;
  }[];
  
  async runTests(tool: Tool): Promise<TestReport> {
    const results = [];
    
    for (const test of this.tests) {
      try {
        await test.setup?.();
        const result = await tool.execute(test.input);
        
        if (test.expectedError) {
          results.push({ name: test.name, passed: false, error: 'Expected error but succeeded' });
        } else {
          const passed = this.matchesExpected(result, test.expectedOutput);
          results.push({ name: test.name, passed });
        }
      } catch (error) {
        if (test.expectedError && error.message.includes(test.expectedError)) {
          results.push({ name: test.name, passed: true });
        } else {
          results.push({ name: test.name, passed: false, error: error.message });
        }
      } finally {
        await test.teardown?.();
      }
    }
    
    return { results };
  }
}

Observability

1. Tool Usage Metrics

typescript
interface ToolMetrics {
  // Usage
  callCount: Counter;
  errorCount: Counter;
  
  // Performance
  latency: Histogram;
  queueDepth: Gauge;
  
  // Reliability
  successRate: number;
  errorRate: number;
  retryRate: number;
}

2. Tool Health Monitoring

typescript
interface ToolHealth {
  async checkToolHealth(tool: Tool): Promise<HealthStatus> {
    // Test basic connectivity
    const connectivity = await this.checkConnectivity(tool);
    
    // Test with simple operation
    const functional = await this.testBasicOperation(tool);
    
    // Check rate limit status
    const rateLimitStatus = await this.checkRateLimits(tool);
    
    return {
      healthy: connectivity && functional,
      connectivity,
      functional,
      rateLimitStatus,
      lastChecked: new Date()
    };
  }
}

Open Questions

  • Standard tool definition format (OpenAPI, JSON Schema, custom)?
  • How to handle tool versioning and backward compatibility?
  • Optimal granularity of tools (coarse vs fine-grained)?
  • How to learn new tools automatically?
  • Balancing tool use vs. direct LLM generation?