61 lines
2.7 KiB
Markdown
61 lines
2.7 KiB
Markdown
# 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
|
|
|
|
- [x] Invalid structure - Health check marks as BROKEN ✓
|
|
- [x] Module not found - Health check marks as BROKEN ✓
|
|
- [ ] Factory function - Partial support (tries common patterns)
|
|
- [x] Missing env var - Import: HEALTHY, Execution: HEALTHY (config issue, not broken)
|
|
- [x] Missing execution context - **Fixed in executor** (commit 0804f1b)
|