From 8b6b550bc17912dcc5f98cff458a4f1d7133389f Mon Sep 17 00:00:00 2001 From: Tim Karlsson Date: Mon, 27 Jul 2026 16:18:52 +0200 Subject: [PATCH 1/2] Add Graceful Tool Failure Handling skill 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. --- .../graceful-tool-failure-handling/README.md | 29 ++++++++ .../graceful-tool-failure-handling/SKILL.md | 67 +++++++++++++++++++ .../metadata.json | 11 +++ 3 files changed, 107 insertions(+) create mode 100644 submissions/graceful-tool-failure-handling/README.md create mode 100644 submissions/graceful-tool-failure-handling/SKILL.md create mode 100644 submissions/graceful-tool-failure-handling/metadata.json diff --git a/submissions/graceful-tool-failure-handling/README.md b/submissions/graceful-tool-failure-handling/README.md new file mode 100644 index 00000000..a2aab6aa --- /dev/null +++ b/submissions/graceful-tool-failure-handling/README.md @@ -0,0 +1,29 @@ +# 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 + +Several skills already build this discipline in for their own domain: +[`it-support-ticket-agent`](../it-support-ticket-agent) never invents a +ticket number a connector didn't return, and +[`company-memory-builder`](../company-memory-builder) 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" +} From f7b993cced3911a3ebd9bd3000f8d55d391e441b Mon Sep 17 00:00:00 2001 From: Tim Karlsson Date: Mon, 27 Jul 2026 21:53:10 +0200 Subject: [PATCH 2/2] Address Copilot review feedback Fixes the issues flagged in the automated review: see PR discussion for details. --- .../graceful-tool-failure-handling/README.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/submissions/graceful-tool-failure-handling/README.md b/submissions/graceful-tool-failure-handling/README.md index a2aab6aa..e6f0de0d 100644 --- a/submissions/graceful-tool-failure-handling/README.md +++ b/submissions/graceful-tool-failure-handling/README.md @@ -9,13 +9,12 @@ instead, and what to do about it. ## Where this pattern already shows up in this gallery -Several skills already build this discipline in for their own domain: -[`it-support-ticket-agent`](../it-support-ticket-agent) never invents a -ticket number a connector didn't return, and -[`company-memory-builder`](../company-memory-builder) 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. +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