Broken Tools Classification

This document tracks the different types of tool failures encountered in the TPMJS executor and the strategies for handling them.

Error Categories

Error Type	Example	Root Cause	Strategy
Invalid structure	`fish-joke-generator`, `@tpmjs/text-transformer`	Not an AI SDK tool (missing `description` or `execute`)	Mark as BROKEN, filter from search results
Module not found	`@thomasdavis/cows@0.0.1`	Package doesn't exist on npm/esm.sh	Mark as BROKEN, consider removing from registry
Factory function	`@tavily/ai-sdk/tavilySearch`	Tool is a factory that needs config to initialize	Need to detect and call with appropriate config
Missing env var	`@exalabs/ai-sdk/webSearch`	Requires API key (e.g., `EXA_API_KEY`) not provided	Import: HEALTHY, Execution: BROKEN with clear error message
Missing execution context	`@parallel-web/ai-sdk-tools/extractTool`	Tool expects `{ abortSignal }` as 2nd arg to `execute()`	Fix executor to pass execution context

Detailed Examples

Invalid Structure

❌ Invalid AI SDK tool structure: {
  hasDescription: false,
  hasExecute: false,
  hasInputSchema: false,
  keys: ["FishJokeSchema", "fishJoker", "createFishJoker", ...]
}

These packages export utility functions or schemas, not AI SDK tools.

Module Not Found

❌ Failed to load tool: TypeError: Module not found "https://esm.sh/@thomasdavis/cows@0.0.1"

Package was registered but doesn't exist on npm or was unpublished.

Factory Function

❌ Tool "tavilySearch" is a factory function but couldn't be initialized.
   Tried: no-args, config object, and single-arg patterns.
   Hint: This tool may require specific configuration. Check package documentation.

Tool exports a factory like tavilySearch({ apiKey }) instead of a ready-to-use tool object.

Missing Env Var

❌ EXA_API_KEY is required. Set it in environment variables or pass it in config.

Tool loaded successfully but execution fails without required credentials.

Missing Execution Context

❌ Tool execution failed: TypeError: Cannot destructure property 'abortSignal' of 'undefined' as it is undefined.
    at Object.execute (https://esm.sh/@parallel-web/ai-sdk-tools@0.1.6/...)

AI SDK tools expect execute(params, { abortSignal, ... }) but executor only passes params.

Resolution Status

Invalid structure - Health check marks as BROKEN ✓
Module not found - Health check marks as BROKEN ✓
Factory function - Partial support (tries common patterns)
Missing env var - Import: HEALTHY, Execution: HEALTHY (config issue, not broken)
Missing execution context - Fixed in executor (commit 0804f1b)

2.7 KiB Raw Blame History