diff --git a/submissions/graceful-tool-failure-handling/README.md b/submissions/graceful-tool-failure-handling/README.md new file mode 100644 index 00000000..e6f0de0d --- /dev/null +++ b/submissions/graceful-tool-failure-handling/README.md @@ -0,0 +1,28 @@ +# Graceful Tool Failure Handling + +A general agent-quality skill for the moment a connector, API call, or file +operation doesn't work. The common failure mode isn't the error itself, it's +what agents do next: continue as if the call had succeeded, quietly drop the +step, or invent a plausible-looking result to fill the gap. This skill makes +the honest response the default: say what was attempted, what happened +instead, and what to do about it. + +## Where this pattern already shows up in this gallery + +This same discipline already shows up domain-specifically elsewhere: an IT +support intake skill that never invents a ticket number a connector didn't +return, or a company-memory skill that says plainly when no persistent +storage is configured rather than pretending memory will carry over. This +skill generalizes that same honesty to any tool call, for agents that don't +already have it built into their domain-specific instructions. + +## How it's different from tool-tracer + +[`tool-tracer`](../tool-tracer) produces a debug log of tool/action calls for +a developer to inspect after the fact. This skill is about the in-conversation +response when a call fails right now, what the user sees and what happens +next, not a diagnostic artifact. + +--- + +Skill by Tim Karlsson (╯°□°)╯︵ ┻━┻ Works 60% of the time, every time. diff --git a/submissions/graceful-tool-failure-handling/SKILL.md b/submissions/graceful-tool-failure-handling/SKILL.md new file mode 100644 index 00000000..c3071ad3 --- /dev/null +++ b/submissions/graceful-tool-failure-handling/SKILL.md @@ -0,0 +1,67 @@ +--- +name: graceful-tool-failure-handling +description: >- + Use this skill whenever a tool call, connector, API request, or file + operation fails, times out, or returns an unexpected result, before + deciding how to respond to the user. Applies any time a needed capability + isn't available or doesn't behave as expected. +--- + +When something doesn't work, say exactly what happened and offer a real +path forward. Never continue as if it worked, and never go silent about it. + +## Instructions + +1. When a tool call fails, times out, returns an error, or returns something + that doesn't look like what was expected, stop and notice it rather than + proceeding on an assumption about what it probably would have returned. + +2. Tell the user plainly: what was attempted, what happened instead, and + whether it's worth retrying. Match the framing to the failure, a timeout + might be worth one retry, a permissions error usually isn't going to + resolve itself on retry, a "not configured" state needs setup, not a + retry. + +3. Never fabricate a result to fill the gap left by a failed tool call. If a + ticket-creation tool fails, don't present a plausible-looking ticket + number. If a search returns nothing, don't answer as if it had returned + something. The honest response is "this didn't work" plus what's known + without it, not a smoothed-over answer that hides the failure. + +4. Distinguish a capability that failed from a capability that was never + available in the first place. "The connector isn't configured on this + platform" and "the connector is configured but returned an error" call for + different responses: the first needs a setup step from an admin, the + second might just need a retry or a different approach. + +5. Offer the best available fallback: a manual version of what the tool would + have done, a different tool that can accomplish the same goal, or a clear + statement of what the user needs to do themselves. Don't just report the + failure and stop there if there's a reasonable way to still help. + +6. If a task depends on a chain of tool calls and one partway through fails, + report exactly how far it got and what's now in an incomplete state, + rather than presenting the whole task as either fully done or fully + failed when the truth is in between. + +7. For a task that already has some safe, completed side effects (a file was + created before a later step failed), say what already happened so nothing + gets silently duplicated or left in an inconsistent state on a retry. + +## Guardrails + +- Never present output that depended on a failed tool call as if the call had + succeeded. +- Never invent an ID, confirmation number, or result that a tool didn't + actually return. +- Don't apologize excessively or dwell on the failure. State it once, clearly, + and move to what can still be done. +- Don't silently retry an operation that has side effects (creating, + sending, or deleting something) without telling the user a retry is + happening, in case the first attempt actually succeeded despite an + ambiguous error. + +## Tone + +Direct and unbothered. A tool failure is routine information to relay, not +something to be defensive or overly apologetic about. diff --git a/submissions/graceful-tool-failure-handling/metadata.json b/submissions/graceful-tool-failure-handling/metadata.json new file mode 100644 index 00000000..0baea327 --- /dev/null +++ b/submissions/graceful-tool-failure-handling/metadata.json @@ -0,0 +1,11 @@ +{ + "name": "Graceful Tool Failure Handling", + "description": "When a tool, connector, or API call fails or misbehaves, states exactly what happened and offers a real fallback, instead of continuing as if it succeeded or fabricating the result it would have returned.", + "platforms": ["Cowork", "Copilot Studio", "Scout"], + "tags": ["agent-quality", "reliability", "error-handling", "transparency", "guardrail"], + "author": "Tim Karlsson", + "authorUrl": "https://github.com/Timziito", + "version": "1.0.0", + "createdAt": "2026-07-27", + "updatedAt": "2026-07-27" +}