diagnose-tool-failure

name	diagnose-tool-failure
description	Pre-classify an agent-tool failure (env, auth, quota, code, data, unknown) before retrying or filing a bug, so the resulting report has a useful hypothesis and the right next step.

Diagnose tool failure

Before retrying or filing an incident with report_incident, classify the failure in one of these buckets and pick the matching next step.

1. Environment / infrastructure

Signals

• Timed out after <N>ms on agent_filesystem_* / agent_terminal_run / agent_coding_run.
• ENV_STARTUP_FAILED, "image not found", "container exited", "no space left on device".
• Sandbox starts but commands return command not found for tools that should be preinstalled.

Action

• Do not keep retrying — the sandbox is the bottleneck.
• Call report_incident with hypothesis: "env".
• Suggested next step in the description: "platform team to retry image pull / increase container start timeout".

2. Auth / integration

Signals

• AUTH_MISSING, INTEGRATION_DISABLED, 401 / 403 from integration calls.
• Tool says " is not connected".

Action

• If the user is in the loop: tell them which integration to (re)connect; do not file an incident.
• If you are running in a dispatched task with no user available: call report_incident with hypothesis: "auth" and route to the integration owner. Do not block work that does not need that service.

3. Quota / rate limit

Signals

• 429, "rate limit", "quota exceeded", RESOURCE_EXHAUSTED.

Action

• Back off (exponential), retry once after the suggested delay.
• If still failing, call report_incident with hypothesis: "quota" and propose the limit / plan that needs raising.

4. Code / schema defect

Signals

• Tool input rejected with "unknown property", "validation failed", or response shape does not match the documented schema.
• Same tool call passes for one input and fails for a near-identical input you can articulate.

Action

• Capture the smallest failing input via reproducible-bug.
• Call report_incident with hypothesis: "code" and attach the minimal repro.

5. Data drift

Signals

• Tool succeeds technically but the result is empty / nonsensical for an input that worked before.
• Search / RAG tools return zero hits for queries that historically returned results.

Action

• Re-run with a known-good input to confirm the tool itself works.
• Call report_incident with hypothesis: "data" if confirmed.

6. Unknown

Signals — None of the above clearly fits.

Action — Do not invent a hypothesis. Call report_incident with hypothesis: "unknown" and include the raw error verbatim.

Output for the reporter

After diagnosis, hand self-report-agent-issue the following so it can populate the report_incident payload cleanly:

• Hypothesis bucket (one of the six above)
• Smallest reliable repro (params + response)
• Whether the failure is blocking
• Whether retry is worth attempting on the platform side