TOOL
Tool and action execution failures.
The TOOL module covers errors when agents interact with external tools, APIs, and services. These errors span the full lifecycle from invoking a tool, through execution, to handling the result.
Categories
INVOCATION
Tool calling failures.
| Code | Severity | Description | Remediation |
|---|---|---|---|
TOOL.INVOCATION.NOT_FOUND | 4 | Tool not found or unavailable | Validate tool availability before planning |
TOOL.INVOCATION.INVALID_ARGS | 4 | Invalid arguments to tool | Validate arguments against schema |
TOOL.INVOCATION.TYPE_MISMATCH | 3 | Argument type mismatch | Implement type coercion |
TOOL.INVOCATION.MISSING_REQUIRED | 4 | Missing required argument | Validate required arguments |
TOOL.INVOCATION.PERMISSION_DENIED | 4 | Permission denied for tool | Check permissions before invocation |
EXECUTION
Tool execution failures.
| Code | Severity | Description | Remediation |
|---|---|---|---|
TOOL.EXECUTION.TIMEOUT | 3 | Tool execution timed out | Implement timeout handling |
TOOL.EXECUTION.CRASHED | 5 | Tool crashed during execution | Add crash recovery |
TOOL.EXECUTION.RATE_LIMITED | 3 | Tool rate limited | Implement rate limit handling with backoff |
TOOL.EXECUTION.DEPENDENCY_FAILED | 4 | Tool dependency failed | Validate dependencies before execution |
TOOL.EXECUTION.RESOURCE_EXHAUSTED | 4 | Tool exhausted resources | Implement resource limits |
Note
The SDK stamps TOOL.EXECUTION.TIMEOUT on a span when it classifies an error as a tool timeout, and that runs today. Diagnosis is held for the beta and fix deployment is gated off, so no fix is generated or applied for this error.
RESULT
Tool result handling failures.
| Code | Severity | Description | Remediation |
|---|---|---|---|
TOOL.RESULT.UNPARSEABLE | 4 | Cannot parse tool result | Implement robust result parsing |
TOOL.RESULT.UNEXPECTED_FORMAT | 3 | Unexpected result format | Validate result schema |
TOOL.RESULT.PARTIAL | 2 | Partial result returned | Handle partial results gracefully |
TOOL.RESULT.EMPTY | 2 | Empty result returned | Handle empty results |
TOOL.RESULT.ERROR_IN_RESULT | 3 | Error embedded in result | Parse and handle result errors |
Example Diagnosis
{
"error_code": "TOOL.EXECUTION.TIMEOUT",
"confidence": 0.95,
"root_cause": "External API response time exceeded the 30s timeout due to upstream service degradation.",
"suggested_fixes": ["retry", "fallback"]
}