{"name":"why_failed","oldName":"explain_error","title":"Why did it fail?","category":"reference","useWhen":"Run whenever a Solana transaction or dry run fails, before retrying. Retrying without knowing why just burns fees.","benefit":{"kind":"money","text":"Explains the failure before the agent retries. 0x1771 from Jupiter means the price moved past the slippage limit, and a blind retry won't fix that."},"description":"Turns a Solana error (hex code, log line or RPC error object) into the plain cause and the fix. Works offline, no chain call.","price":"$0.01","priceText":"25 free calls a day, then $0.01 USDC per call (x402)","http":{"method":"POST","path":"/api/tools/why_failed","body":"JSON object with the inputs below"},"mcp":{"method":"tools/call","name":"why_failed"},"inputs":[{"name":"error","type":"string or object","required":true,"lookingFor":"The error exactly as you got it: \"custom program error: 0x1771\", \"InsufficientFundsForRent\", or the RPC error object.","whereToGet":"From your send or RPC error, a dry-run result, a wallet message, or history."},{"name":"program","type":"string (base58 address)","required":false,"lookingFor":"The program that failed. Needed to read custom error codes correctly.","whereToGet":"From the log line \"Program <address> failed\", or from explain_tx."}],"outputs":[{"field":"known","type":"boolean","is":"Whether we know this error.","howWorkedOut":"At least one explanation matched."},{"field":"failed_step","type":"number | null","is":"Which step in the transaction failed (counting from 0).","howWorkedOut":"Read from InstructionError [step, ...] or \"instruction N\" in the text."},{"field":"program","type":"string | null","is":"The program the error was read against.","howWorkedOut":"Your input, or the program named in the error text."},{"field":"explanations[].name","type":"string","is":"The error's official name.","howWorkedOut":"Matched against tables for transaction errors, instruction errors, the System and Token programs, Anchor and selected programs."},{"field":"explanations[].scope","type":"string","is":"Which layer raised it: transaction, instruction, system_program, token_program, anchor_framework or program_specific.","howWorkedOut":"Which table matched."},{"field":"explanations[].meaning","type":"string","is":"What went wrong, in plain words.","howWorkedOut":"Written by hand."},{"field":"explanations[].likely_cause","type":"string","is":"The usual reason it happens.","howWorkedOut":"Written by hand."},{"field":"explanations[].fix","type":"string","is":"What to change before retrying, often naming the tool that helps.","howWorkedOut":"Written by hand."},{"field":"next_step","type":"string","is":"The one thing to do next.","howWorkedOut":"The first explanation's fix, or how to find the failing program when the error is unknown."}],"notes":["Custom codes 6000 and up are defined by each program. Without program we say so instead of guessing."],"inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"anyOf":[{"type":"string"},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}]},"program":{"type":"string"}},"required":["error"]}}