[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6MMDVFN7M88K329N7J91WB6":3,"skill-same:01M6MMDVFN7M88K329N7J91WB6":82},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":28,"publishedAt":46,"linkOnly":47,"markdownContent":48,"markdownBody":49,"frontMatter":50,"refName":53,"commitSha":54,"skillDirectory":55,"forksCount":56,"repositoryHtmlUrl":57,"repositoryHomepageUrl":58,"ownerHtmlUrl":59,"ownerBlogUrl":60,"ownerDescription":61,"updatedAt":62,"install":63,"resources":75},"01M6MMDVFN7M88K329N7J91WB6","tool-design-errors",null,"Design actionable agent tool errors, ambiguity handling, retry guidance, and fallback behavior, or debug an agent that loops on or misreads a failing tool.","hashgraph-online\u002Fawesome-codex-plugins","hashgraph-online","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F160371962?v=4","01M6CNB6NRJVNNGN14TR01Q6D3","HOL (Hashgraph Online)","01M6JT1HSKKG9V68KQAQGBA7XP",1571,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fruntypelabs\u002Fskills\u002Fskills\u002Ftool-design-errors\u002FSKILL.md",[18,23],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000015","视觉设计","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":26,"taxonomyTypeDesc":27},"01JBSEEDCAT000000000000032","设计师","PROFESSION","适用职业",[29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45],"tool","tool design","tool design errors","design","errors","actionable","failing","agent tool","true","ambiguity","retry","loops","paths","fallback","guidance","behavior","debug","2026-11-10 10:12:30",false,"---\nname: tool-design-errors\ndescription: 'Design actionable agent tool errors, ambiguity handling, retry guidance, and fallback behavior, or debug an agent that loops on or misreads a failing tool.'\nuser-invocable: true\nargument-hint: '[tool whose failure paths to design]'\n---\n\n# Tool error design\n\nAn agent that receives only `429` either retries in a tight loop or gives up. An agent\nthat receives \"Rate limited. Wait 30 seconds, or reduce `batchSize` to 50 and retry\"\nmakes a better second call. Give every error a class, a reason, and the next call to\nmake. Design the failure paths with the same care as the success path.\n\n## Procedure\n\n1. **List every way the tool can fail**: bad input, missing prerequisite, not found,\n   ambiguous match, upstream unavailable, rate limit, timeout, permission denied,\n   missing scope, partial completion.\n2. **Classify each failure** into exactly one class (below). The class tells the agent\n   whether to retry, change the call, ask the user, or have the user re-authenticate.\n3. **Write the recovery text** for each failure: what went wrong, why, and the exact\n   next call.\n4. **Decide the ambiguity policy** for any natural-identifier input: thresholds for\n   auto-accept, confirm, and reject.\n5. **Decide the degradation policy** for multi-source or multi-step tools: what the\n   tool returns when part of the work fails.\n6. **Test by reading the error cold**: could an agent with only the tool description\n   and this error message make a better second call? If not, rewrite it.\n\n## Rules with examples\n\nThe names in parentheses are the pattern names that the tool-design skills share.\n\nAll examples use one error envelope: `class`, `message`, `reason`, `recoverySteps`,\nand, where they apply, `retryAfterSeconds`, `options`, or `suggestions`. Use the same\nenvelope in every tool in the set.\n\n### Every error carries a class (Error Classification)\n\n| Class          | Meaning                                 | Agent should                     |\n| -------------- | --------------------------------------- | -------------------------------- |\n| `retryable`    | Transient. Likely to succeed later      | Wait `retryAfterSeconds`, retry  |\n| `permanent`    | Will not succeed without a changed call | Change parameters or tool        |\n| `userInput`    | Needs a human decision                  | Ask the user                     |\n| `authRequired` | Credential or scope missing or expired  | Ask the user to reconnect access |\n\nUse the same class vocabulary in every tool in the set. Map upstream errors onto it\ninside the tool, so the agent never sees vendor-specific codes. Retryable errors always\ncarry `retryAfterSeconds`.\n\n### Every error guides recovery (Recovery Guide)\n\nUse structure, not prose:\n\n```json\n{\n  \"class\": \"permanent\",\n  \"message\": \"User not found\",\n  \"reason\": \"No user matches \\\"jon smith\\\"\",\n  \"recoverySteps\": [\n    \"Call search_users(query=\\\"jon smith\\\") to list candidates\",\n    \"Retry with the user's email address instead of a display name\"\n  ],\n  \"suggestions\": [{ \"id\": \"usr_1\", \"name\": \"Jon Smyth\", \"email\": \"jon@example.com\" }]\n}\n```\n\nInclude concrete tool names and parameter values, not \"check your input\". Name\nalternative tools when one exists. For a rate limit, say how long to wait and what size\nto reduce.\n\n### Ambiguity returns options, never a guess (Confirmation Request)\n\nWhen a natural identifier matches more than one record, do not pick one. Return the\nmatches with enough detail to tell them apart (name, email, last activity), cap the\nlist at five to ten, and state the exact call to make for each option:\n\n```json\n{\n  \"class\": \"userInput\",\n  \"message\": \"3 contacts match \\\"Alex\\\"\",\n  \"reason\": \"The name \\\"Alex\\\" is not unique\",\n  \"options\": [\n    { \"contactId\": \"c_1\", \"name\": \"Alex Kim\", \"email\": \"alex.kim@example.com\" },\n    { \"contactId\": \"c_2\", \"name\": \"Alex Reyes\", \"email\": \"areyes@example.com\" }\n  ],\n  \"recoverySteps\": [\"Call update_contact(contactId=...) with one of the ids above\"]\n}\n```\n\nZero matches is a `permanent` error with suggestions, not an empty list that reads as\nsuccess.\n\n### Thresholds decide when to ask (Fuzzy Match Threshold)\n\nConfirming every match is slow. Never confirming is dangerous. Pick thresholds and\ndocument them. A reasonable starting point:\n\n- Above 90% confidence: auto-accept, and log the match for audit.\n- 50% to 90%: return the candidates as a confirmation request.\n- Below 50%: reject with a \"try a different identifier\" recovery step.\n\nExpose the threshold as a parameter with a safe default when callers need to tune it.\nCommand tools with irreversible effects should set the auto-accept bar higher than\nquery tools.\n\n### Return what worked (Graceful Degradation)\n\nA tool that aggregates from several sources or performs several steps returns the parts\nthat succeeded, names the parts that failed, states completeness, and says how to get\nthe rest:\n\n```json\n{\n  \"completeness\": \"partial\",\n  \"crm\": { \"...\": \"...\" },\n  \"billing\": null,\n  \"errors\": [\n    {\n      \"source\": \"billing\",\n      \"class\": \"retryable\",\n      \"reason\": \"Billing service unavailable (503)\",\n      \"retryAfterSeconds\": 60\n    }\n  ],\n  \"recoverySteps\": [\"Call get_unified_profile again in 60 seconds for billing data\"]\n}\n```\n\nA total failure that hides a successful partial result wastes the work already done and\nthe tokens already spent.\n\n### Provide an alternative when the primary is down (Fallback Tool)\n\nFor critical capabilities, define a fallback order (`slack`, then `email`, then `sms`).\nEither switch transparently and report `channelUsed` and `wasFallback: true`, or return\na `permanent` error that names the fallback tool to call. Never fall back silently to a\ncommand whose side effects differ from the one requested.\n\n### Timeouts are errors too\n\nA timeout returns a `retryable` error that says what timed out, how long the limit is,\nwhether partial results are attached, and whether an async variant exists. See\n`tool-design-execution` for the boundary itself.\n\n## Anti-patterns\n\n- Passing the upstream exception string or HTTP status through as the error.\n- \"Invalid input\" with no field name and no valid values.\n- Picking the first fuzzy match on a command tool.\n- Throwing on the first failed item in a batch.\n- A retryable error with no `retryAfterSeconds`, so the agent retries immediately.\n- Success-shaped responses for failures (`{ \"items\": [] }` when the query was invalid).\n- Recovery text written for the developer (\"see logs\") instead of the agent.\n\n## On Runtype\n\n### What the model receives\n\n- **Runtype classifies every failed tool call.** The model receives\n  `{ error, errorType }`, where `errorType` is one of `auth`, `rate_limited`,\n  `upstream_4xx`, `upstream_5xx`, `timeout`, `invalid_args`, `not_configured`,\n  `aborted`, or `unknown`. Runtype sets it from the HTTP status first, then from the\n  error text. It does not tell the model whether to retry. Your classes add to\n  `errorType`: return the matching status (429 with `retryable`, 401 or 403 with\n  `authRequired`, 400 or 422 with `permanent`) and put your class and recovery steps\n  in the error body.\n- **For an `external` tool, shape the error in your own endpoint.** Return a non-2xx\n  status and a compact JSON body. The model sees\n  `External tool \"TOOL_NAME\" failed: HTTP STATUS — ` followed by the first 500\n  characters of the body. Response headers such as `Retry-After` are\n  dropped. Put `class`, `retryAfterSeconds`, and the first recovery step at the top of\n  the body. A 2xx response that carries an error payload counts as a success and gets\n  no `errorType`.\n- **To classify a third-party API you do not control**, wrap the call in a `flow` tool.\n  An `api-call` step with `errorHandling: \"continue\"` writes its `defaultValue` when\n  the call fails, so set `defaultValue` to a structured error object, and add a\n  `transform-data` step that gives success and failure one result shape. If the step\n  has a `responseMapping`, the mapping also applies to `defaultValue`, so map the error\n  fields too. The step cannot read the upstream status, so the fallback object carries\n  one fixed class. A `custom` tool has no network egress unless it opts in with\n  `networkAccess` (and `secrets` for credentials); then it can make the call and shape\n  the failure class itself.\n- **For an MCP server tool, put the class and recovery steps in the content text.**\n  Runtype passes the `content` of a `tools\u002Fcall` result to the model and does not read\n  `isError`, so a result with `isError: true` is recorded as a successful call. A\n  non-2xx HTTP response or a JSON-RPC error is still reported as a failed call.\n- **`external` tool calls time out after 30 seconds**, and the model receives a\n  `timeout` error. For slower upstreams, use a detached `subagent` tool (see\n  `tool-design-execution`).\n\n### Errors Runtype writes for you\n\nTell the agent, in its instructions, how to handle the errors that Runtype writes\nitself:\n\n- A tool call that the user denied at approval. It cannot be retried.\n- A call interrupted mid-run on a resumed turn. Its effects are unknown, so the agent\n  must check whether the write happened before it retries. Set `idempotent: true` on\n  read-only runtime tools so that Runtype can safely run an interrupted call again.\n  MCP tools follow the server's `readOnlyHint` and `idempotentHint` annotations.\n- Missing secrets or an MCP server that is not configured (`not_configured`). The\n  agent cannot fix these. It should tell the user what to set up.\n\nFor MCP servers that use OAuth2, Runtype refreshes an expired token and retries once\nafter a 401. Use `authRequired` only when the user must act. For an MCP server, have\nthe recovery step tell the user to reconnect the server from **Tools**.\n\n### Confirmation requests on chat surfaces\n\nBehind a Persona widget, expose the built-in local tools\n(`features.askUserQuestion.expose`, `features.suggestReplies.expose`). An ambiguous\nmatch then becomes a rendered choice that the user taps, not a JSON options list that\nthe model has to narrate. Elsewhere, return the options in the tool result as shown\nabove.\n\n### Flow step defaults\n\nSome flow steps continue when they fail. This partial list shows the behavior when\n`errorHandling` is unset:\n\n- `fetch-url`, `api-call`, `crawl`, `search`, and `transform-data` continue and write\n  `defaultValue`.\n- `paginate-api` fails the step.\n- `upsert-record` reports `success: false` and writes no output when its source\n  variable is missing or does not resolve to a JSON object. `update-record` does the\n  same when it cannot find the target record. Both continue with `defaultValue` on\n  other failures.\n- A `tool-call` step ignores `errorHandling`. It uses `config.onError`, which fails the\n  step by default. With `onError: \"continue\"`, it writes `{ error, result: null }`.\n\nSet `errorHandling` to `\"fail\"` or `\"continue\"` explicitly on any step where a silent\ncontinue would hide a real failure from the agent.\n\n### Pauses and retries\n\n- The platform's own pauses are not errors. An `await` event means the run is waiting\n  on a person or the client: an approval, a client tool, an elicitation, or a detached\n  run. Its `awaitReason` separates pauses that resume on their own from pauses that\n  the client must resolve. A surface must render them as pauses, not as failures.\n- The model retries failed tools, not the platform. `retryAfterSeconds` in the result\n  is what stops a tight loop. Also set the agent's **Max turns** and **Cost budget\n  (USD)** so that a tool that keeps failing cannot loop without limit.\n- Test failure paths with `execute_tool` and deliberately wrong inputs before you\n  attach the tool to an agent. Capture real failures as eval cases with\n  `add_eval_case_from_execution` so that the fix stays pinned.\n\nSee also [Agent tools: Error handling](https:\u002F\u002Fdocs.runtype.com\u002Fuser-guide\u002Fagents\u002Fagent-tools#error-handling),\n[Runtime tools: Tool replay after an interrupted turn](https:\u002F\u002Fdocs.runtype.com\u002Fdeveloper-guides\u002Fguides\u002Fruntime-tools#tool-replay-after-an-interrupted-turn),\nand [Runtime tools: Pause and resume on an agent dispatch](https:\u002F\u002Fdocs.runtype.com\u002Fdeveloper-guides\u002Fguides\u002Fruntime-tools#pause-and-resume-on-an-agent-dispatch).\n","# Tool error design\n\nAn agent that receives only `429` either retries in a tight loop or gives up. An agent\nthat receives \"Rate limited. Wait 30 seconds, or reduce `batchSize` to 50 and retry\"\nmakes a better second call. Give every error a class, a reason, and the next call to\nmake. Design the failure paths with the same care as the success path.\n\n## Procedure\n\n1. **List every way the tool can fail**: bad input, missing prerequisite, not found,\n   ambiguous match, upstream unavailable, rate limit, timeout, permission denied,\n   missing scope, partial completion.\n2. **Classify each failure** into exactly one class (below). The class tells the agent\n   whether to retry, change the call, ask the user, or have the user re-authenticate.\n3. **Write the recovery text** for each failure: what went wrong, why, and the exact\n   next call.\n4. **Decide the ambiguity policy** for any natural-identifier input: thresholds for\n   auto-accept, confirm, and reject.\n5. **Decide the degradation policy** for multi-source or multi-step tools: what the\n   tool returns when part of the work fails.\n6. **Test by reading the error cold**: could an agent with only the tool description\n   and this error message make a better second call? If not, rewrite it.\n\n## Rules with examples\n\nThe names in parentheses are the pattern names that the tool-design skills share.\n\nAll examples use one error envelope: `class`, `message`, `reason`, `recoverySteps`,\nand, where they apply, `retryAfterSeconds`, `options`, or `suggestions`. Use the same\nenvelope in every tool in the set.\n\n### Every error carries a class (Error Classification)\n\n| Class          | Meaning                                 | Agent should                     |\n| -------------- | --------------------------------------- | -------------------------------- |\n| `retryable`    | Transient. Likely to succeed later      | Wait `retryAfterSeconds`, retry  |\n| `permanent`    | Will not succeed without a changed call | Change parameters or tool        |\n| `userInput`    | Needs a human decision                  | Ask the user                     |\n| `authRequired` | Credential or scope missing or expired  | Ask the user to reconnect access |\n\nUse the same class vocabulary in every tool in the set. Map upstream errors onto it\ninside the tool, so the agent never sees vendor-specific codes. Retryable errors always\ncarry `retryAfterSeconds`.\n\n### Every error guides recovery (Recovery Guide)\n\nUse structure, not prose:\n\n```json\n{\n  \"class\": \"permanent\",\n  \"message\": \"User not found\",\n  \"reason\": \"No user matches \\\"jon smith\\\"\",\n  \"recoverySteps\": [\n    \"Call search_users(query=\\\"jon smith\\\") to list candidates\",\n    \"Retry with the user's email address instead of a display name\"\n  ],\n  \"suggestions\": [{ \"id\": \"usr_1\", \"name\": \"Jon Smyth\", \"email\": \"jon@example.com\" }]\n}\n```\n\nInclude concrete tool names and parameter values, not \"check your input\". Name\nalternative tools when one exists. For a rate limit, say how long to wait and what size\nto reduce.\n\n### Ambiguity returns options, never a guess (Confirmation Request)\n\nWhen a natural identifier matches more than one record, do not pick one. Return the\nmatches with enough detail to tell them apart (name, email, last activity), cap the\nlist at five to ten, and state the exact call to make for each option:\n\n```json\n{\n  \"class\": \"userInput\",\n  \"message\": \"3 contacts match \\\"Alex\\\"\",\n  \"reason\": \"The name \\\"Alex\\\" is not unique\",\n  \"options\": [\n    { \"contactId\": \"c_1\", \"name\": \"Alex Kim\", \"email\": \"alex.kim@example.com\" },\n    { \"contactId\": \"c_2\", \"name\": \"Alex Reyes\", \"email\": \"areyes@example.com\" }\n  ],\n  \"recoverySteps\": [\"Call update_contact(contactId=...) with one of the ids above\"]\n}\n```\n\nZero matches is a `permanent` error with suggestions, not an empty list that reads as\nsuccess.\n\n### Thresholds decide when to ask (Fuzzy Match Threshold)\n\nConfirming every match is slow. Never confirming is dangerous. Pick thresholds and\ndocument them. A reasonable starting point:\n\n- Above 90% confidence: auto-accept, and log the match for audit.\n- 50% to 90%: return the candidates as a confirmation request.\n- Below 50%: reject with a \"try a different identifier\" recovery step.\n\nExpose the threshold as a parameter with a safe default when callers need to tune it.\nCommand tools with irreversible effects should set the auto-accept bar higher than\nquery tools.\n\n### Return what worked (Graceful Degradation)\n\nA tool that aggregates from several sources or performs several steps returns the parts\nthat succeeded, names the parts that failed, states completeness, and says how to get\nthe rest:\n\n```json\n{\n  \"completeness\": \"partial\",\n  \"crm\": { \"...\": \"...\" },\n  \"billing\": null,\n  \"errors\": [\n    {\n      \"source\": \"billing\",\n      \"class\": \"retryable\",\n      \"reason\": \"Billing service unavailable (503)\",\n      \"retryAfterSeconds\": 60\n    }\n  ],\n  \"recoverySteps\": [\"Call get_unified_profile again in 60 seconds for billing data\"]\n}\n```\n\nA total failure that hides a successful partial result wastes the work already done and\nthe tokens already spent.\n\n### Provide an alternative when the primary is down (Fallback Tool)\n\nFor critical capabilities, define a fallback order (`slack`, then `email`, then `sms`).\nEither switch transparently and report `channelUsed` and `wasFallback: true`, or return\na `permanent` error that names the fallback tool to call. Never fall back silently to a\ncommand whose side effects differ from the one requested.\n\n### Timeouts are errors too\n\nA timeout returns a `retryable` error that says what timed out, how long the limit is,\nwhether partial results are attached, and whether an async variant exists. See\n`tool-design-execution` for the boundary itself.\n\n## Anti-patterns\n\n- Passing the upstream exception string or HTTP status through as the error.\n- \"Invalid input\" with no field name and no valid values.\n- Picking the first fuzzy match on a command tool.\n- Throwing on the first failed item in a batch.\n- A retryable error with no `retryAfterSeconds`, so the agent retries immediately.\n- Success-shaped responses for failures (`{ \"items\": [] }` when the query was invalid).\n- Recovery text written for the developer (\"see logs\") instead of the agent.\n\n## On Runtype\n\n### What the model receives\n\n- **Runtype classifies every failed tool call.** The model receives\n  `{ error, errorType }`, where `errorType` is one of `auth`, `rate_limited`,\n  `upstream_4xx`, `upstream_5xx`, `timeout`, `invalid_args`, `not_configured`,\n  `aborted`, or `unknown`. Runtype sets it from the HTTP status first, then from the\n  error text. It does not tell the model whether to retry. Your classes add to\n  `errorType`: return the matching status (429 with `retryable`, 401 or 403 with\n  `authRequired`, 400 or 422 with `permanent`) and put your class and recovery steps\n  in the error body.\n- **For an `external` tool, shape the error in your own endpoint.** Return a non-2xx\n  status and a compact JSON body. The model sees\n  `External tool \"TOOL_NAME\" failed: HTTP STATUS — ` followed by the first 500\n  characters of the body. Response headers such as `Retry-After` are\n  dropped. Put `class`, `retryAfterSeconds`, and the first recovery step at the top of\n  the body. A 2xx response that carries an error payload counts as a success and gets\n  no `errorType`.\n- **To classify a third-party API you do not control**, wrap the call in a `flow` tool.\n  An `api-call` step with `errorHandling: \"continue\"` writes its `defaultValue` when\n  the call fails, so set `defaultValue` to a structured error object, and add a\n  `transform-data` step that gives success and failure one result shape. If the step\n  has a `responseMapping`, the mapping also applies to `defaultValue`, so map the error\n  fields too. The step cannot read the upstream status, so the fallback object carries\n  one fixed class. A `custom` tool has no network egress unless it opts in with\n  `networkAccess` (and `secrets` for credentials); then it can make the call and shape\n  the failure class itself.\n- **For an MCP server tool, put the class and recovery steps in the content text.**\n  Runtype passes the `content` of a `tools\u002Fcall` result to the model and does not read\n  `isError`, so a result with `isError: true` is recorded as a successful call. A\n  non-2xx HTTP response or a JSON-RPC error is still reported as a failed call.\n- **`external` tool calls time out after 30 seconds**, and the model receives a\n  `timeout` error. For slower upstreams, use a detached `subagent` tool (see\n  `tool-design-execution`).\n\n### Errors Runtype writes for you\n\nTell the agent, in its instructions, how to handle the errors that Runtype writes\nitself:\n\n- A tool call that the user denied at approval. It cannot be retried.\n- A call interrupted mid-run on a resumed turn. Its effects are unknown, so the agent\n  must check whether the write happened before it retries. Set `idempotent: true` on\n  read-only runtime tools so that Runtype can safely run an interrupted call again.\n  MCP tools follow the server's `readOnlyHint` and `idempotentHint` annotations.\n- Missing secrets or an MCP server that is not configured (`not_configured`). The\n  agent cannot fix these. It should tell the user what to set up.\n\nFor MCP servers that use OAuth2, Runtype refreshes an expired token and retries once\nafter a 401. Use `authRequired` only when the user must act. For an MCP server, have\nthe recovery step tell the user to reconnect the server from **Tools**.\n\n### Confirmation requests on chat surfaces\n\nBehind a Persona widget, expose the built-in local tools\n(`features.askUserQuestion.expose`, `features.suggestReplies.expose`). An ambiguous\nmatch then becomes a rendered choice that the user taps, not a JSON options list that\nthe model has to narrate. Elsewhere, return the options in the tool result as shown\nabove.\n\n### Flow step defaults\n\nSome flow steps continue when they fail. This partial list shows the behavior when\n`errorHandling` is unset:\n\n- `fetch-url`, `api-call`, `crawl`, `search`, and `transform-data` continue and write\n  `defaultValue`.\n- `paginate-api` fails the step.\n- `upsert-record` reports `success: false` and writes no output when its source\n  variable is missing or does not resolve to a JSON object. `update-record` does the\n  same when it cannot find the target record. Both continue with `defaultValue` on\n  other failures.\n- A `tool-call` step ignores `errorHandling`. It uses `config.onError`, which fails the\n  step by default. With `onError: \"continue\"`, it writes `{ error, result: null }`.\n\nSet `errorHandling` to `\"fail\"` or `\"continue\"` explicitly on any step where a silent\ncontinue would hide a real failure from the agent.\n\n### Pauses and retries\n\n- The platform's own pauses are not errors. An `await` event means the run is waiting\n  on a person or the client: an approval, a client tool, an elicitation, or a detached\n  run. Its `awaitReason` separates pauses that resume on their own from pauses that\n  the client must resolve. A surface must render them as pauses, not as failures.\n- The model retries failed tools, not the platform. `retryAfterSeconds` in the result\n  is what stops a tight loop. Also set the agent's **Max turns** and **Cost budget\n  (USD)** so that a tool that keeps failing cannot loop without limit.\n- Test failure paths with `execute_tool` and deliberately wrong inputs before you\n  attach the tool to an agent. Capture real failures as eval cases with\n  `add_eval_case_from_execution` so that the fix stays pinned.\n\nSee also [Agent tools: Error handling](https:\u002F\u002Fdocs.runtype.com\u002Fuser-guide\u002Fagents\u002Fagent-tools#error-handling),\n[Runtime tools: Tool replay after an interrupted turn](https:\u002F\u002Fdocs.runtype.com\u002Fdeveloper-guides\u002Fguides\u002Fruntime-tools#tool-replay-after-an-interrupted-turn),\nand [Runtime tools: Pause and resume on an agent dispatch](https:\u002F\u002Fdocs.runtype.com\u002Fdeveloper-guides\u002Fguides\u002Fruntime-tools#pause-and-resume-on-an-agent-dispatch).\n",{"name":5,"description":7,"argument-hint":51,"user-invocable":52},"[tool whose failure paths to design]",true,"main","2b63f856ce19c2a797929cacabd9e0fc936812fa","plugins\u002Fruntypelabs\u002Fskills\u002Fskills\u002Ftool-design-errors",490,"https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins","https:\u002F\u002Fhol.org\u002Fplugins\u002Fbest-codex-plugins","https:\u002F\u002Fgithub.com\u002Fhashgraph-online","https:\u002F\u002Fhol.org","Open-source standards and developer tools for interoperable AI agents: discovery, identity, communication, payments, privacy and security.","2026-11-14 02:12:02",{"source":8,"skillName":5,"commands":64,"prompt":74,"zipAvailable":52},[65,68,71],{"tool":66,"command":67},"npx","npx skills add hashgraph-online\u002Fawesome-codex-plugins --skill tool-design-errors",{"tool":69,"command":70},"bunx","bunx skills add hashgraph-online\u002Fawesome-codex-plugins --skill tool-design-errors",{"tool":72,"command":73},"pnpm","pnpm dlx skills add hashgraph-online\u002Fawesome-codex-plugins --skill tool-design-errors","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fruntypelabs\u002Fskills\u002Fskills\u002Ftool-design-errors\u002FSKILL.md",[76],{"path":77,"resourceType":78,"resourceTypeDesc":79,"sizeBytes":80,"sourceHtmlUrl":81},"agents\u002Fopenai.yaml","REFERENCE","参考文档",292,"https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fruntypelabs\u002Fskills\u002Fskills\u002Ftool-design-errors\u002Fagents\u002Fopenai.yaml",[83,91,98,105,131,156],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":90},"01M746ZWACVKMZ1BJXJZHYJSSX","migrate-to-e2e","Moves an existing Playwright, Cypress, Selenium, Appium, Detox, Maestro, or TesterArmy suite to e2e one slice at a time, with the old suite running beside the new one until each ported test is proven. Keeps a MIGRATION.md progress file so any later session resumes where the last stopped. Optionally plants a defect to show both suites catch it. Use for \u002Fmigrate-to-e2e, \"migrate our tests to e2e\", \"port these Maestro flows\", \"move our TesterArmy tests\", or when a project has an e2e config and an older suite still running.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Ftester-army\u002Fe2e\u002Fskills\u002Fmigrate-to-e2e\u002FSKILL.md",[],[],"2026-11-11 15:11:14",{"skillNo":92,"name":93,"nameZh":6,"description":94,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":95,"categories":96,"keywords":97,"publishedAt":90},"01M746ZPTAX1Q0FBKAB1CYND7E","e2e","Writes, runs, and debugs end-to-end tests for web and mobile apps with e2e, the agentic test runner, which mixes agent.act goals with exact locator assertions on a Playwright browser or an iOS or Android device. Also drives a project's running app live over the e2e MCP server to look at a screen, check a UI change, take a screenshot or record a video, and try a locator; and runs bug bashes, parallel e2e explore runs with each bug proven by a repro test. Use when a project depends on e2e or has an e2e.config.ts, when asked for end-to-end, browser, mobile, or agentic UI tests, to check a change in the running app, to QA or bug bash an app or branch, or when an e2e run fails.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Ftester-army\u002Fe2e\u002Fskills\u002Fe2e\u002FSKILL.md",[],[],{"skillNo":99,"name":100,"nameZh":6,"description":101,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":102,"categories":103,"keywords":104,"publishedAt":90},"01M746ZJN784HVHMDP9MQGCSGG","create-verification-skill","Generate a project-local verify-\u003Capp> skill on top of e2e, so any coding agent can launch the app, check it is worth driving, exercise a feature the way a user does, keep evidence, and bug bash it. Writes the skill, a feature map with one explore charter per feature, and proves it once. Use for \u002Fcreate-verification-skill, \"make a verification skill for this repo\", or when a project has no scripted way to prove UI behavior.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Ftester-army\u002Fe2e\u002Fskills\u002Fcreate-verification-skill\u002FSKILL.md",[],[],{"skillNo":106,"name":107,"nameZh":6,"description":108,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":109,"categories":110,"keywords":111,"publishedAt":46},"01M716A6ETNB9B1SQ3GXZC75VR","deja-search","deja-vu memory — search the user's past AI coding sessions with the deja CLI. Holds what they already settled and never wrote into the repo (naming rules, banned or already-tried tools, required checks before merge, preferred values, who owns what). Use before your first edit in a task, before you call a change done or ready to merge, before you recommend a tool, library, design or reviewer, before re-debugging an error that may already be solved, when they say 'didn't we fix this before', 'what did we decide about X' or 'I already have that', and before telling them something on this machine does not exist.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fvshulcz\u002Fdeja-vu\u002Fskills\u002Fdeja-search\u002FSKILL.md",[],[112,113,114,115,116,117,118,119,120,32,121,122,123,124,125,126,127,128,129,130],"search","deja search","never","error","ready","memory","re","decide","fix","debugging","when","you","done","reviewer","io","change","cli","merge","past",{"skillNo":132,"name":133,"nameZh":6,"description":134,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":135,"categories":136,"keywords":137,"publishedAt":46},"01M716A3J2W5SENSE9VGMXB375","deja-reflect","End-of-session reflection and memory curation with deja-vu. Review what was decided, what commands broke and what repaired them, and record durable project rules or decisions with deja remember so the next session starts with them.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fvshulcz\u002Fdeja-vu\u002Fskills\u002Fdeja-reflect\u002FSKILL.md",[],[138,139,140,126,141,142,143,144,145,146,147,148,149,150,117,151,152,153,154,155],"deja reflect","reflect","review","with","record","github","next","https","node","Rules","decisions","brew","remember","project rules","project","session","end","reflection",{"skillNo":157,"name":158,"nameZh":6,"description":159,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":160,"categories":161,"keywords":171,"publishedAt":46},"01M715T3RR4BAYSR57HPPTJ0PF","revid","Make, edit, export and post AI videos with Revid (revid.ai) through the Revid MCP server. Use whenever the user wants a short-form or long-form video made (from an idea, a script, a URL, an article, a PDF, a tweet, a product page, their own clips, or a song), wants to find what is going viral on TikTok, YouTube, Instagram or X before making something, wants to edit or re-export an existing Revid project, generate a standalone AI image or clip, make a series episode, or publish and schedule a finished video to connected social accounts. Covers setup (hosted MCP with OAuth, or an API key), the 36 tools, credits, polling and the rules for publishing. Routes to the more specific revid-* skills when one fits.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Ftmakersas\u002Frevid-skills\u002Fskills\u002Frevid\u002FSKILL.md",[162,165,168],{"categoryNo":163,"categoryName":164,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000016","图像与多媒体",{"categoryNo":166,"categoryName":167,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":169,"categoryName":170,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000010","后端与接口",[158,172,173,174,175,176,177,152,178,118,179,180,181,182,122,183,184,185,186,187],"URL","Video","short-form","standalone","PDF","viral","tiktok","short","social","MCP","song","image","mcp server","schedule","api","publish"]