| name | self-report-agent-issue |
| description | When your own tools fail (sandbox, MCP, integration, timeouts), diagnose, attach evidence, and file a structured Jira incident instead of retrying silently or pretending the task succeeded. |
Self-report agent issue
When your own tools fail mid-task — sandbox / filesystem / terminal / MCP
/ integration timeouts, auth errors, env setup failures — file a single
structured incident via the report_incident system tool.
You MUST NOT call jira_create_task, notion_*, planning_tasks_bulk_create,
or any other task-manager tool directly for runtime failures. The platform
chooses where the report fans out (PolyGents observability + customer-
configured destinations). Your job is one call to report_incident.
Procedure
- Stop the failing flow. Do not retry indefinitely (max 2 retries unless
you can articulate why the error is a transient network blip).
- Diagnose the failure with the
diagnose-tool-failure skill before
reporting (env / auth / quota / code / data / unknown).
- Tell the user in chat what failed and that you are filing a report.
Stay concrete: tool name, error code, what you were trying to do.
- Attach evidence first. For each significant log / failing artifact
you can read from the agent filesystem, push it to the initiative with
initiative_file_upload and capture the returned id. Pass those ids in
evidence_file_ids.
- Call
report_incident with the payload below.
- Tell the user the returned
incidentKey and a short next-step
suggestion (retry once the platform fixes , switch to tool,
etc.).
When to invoke
Invoke this skill after a retry you can justify when any of the following
occurs:
agent_filesystem_*, agent_coding_run, agent_terminal_run returns a
timeout, ENV_STARTUP_FAILED, IMAGE_PULL_FAILED, OOM, or similar infra
error.browserbase_fetch returns NAVIGATE_FAILED / WAIT_FAILED /
EXTRACT_TEXT_FAILED repeatedly on a stable URL.- Any MCP / integration tool returns
AUTH_MISSING /
INTEGRATION_DISABLED for an integration the user has clearly connected.
- A tool returns 5xx-class errors, schema mismatches, or non-JSON output
three times in a row.
- A tool you expected to exist returns "unknown tool" (registry drift).
If retries succeed, do not file. Only report when the failure is
persistent or reproducible-by-the-platform.
report_incident payload
{
"category": "issue",
"hypothesis": "env",
"severity": "high",
"summary": "[Agent <name>] <tool> failed: <error code>",
"description": "<structured markdown — see template below>",
"failing_tool": "agent_filesystem_write",
"error_code": "TIMEOUT",
"evidence_file_ids": ["<from initiative_file_upload>"],
"blocking": true
}
category: always "issue" for runtime failures. Use "product_bug"
only when you have verified a defect in the customer-owned product.hypothesis: one of env | auth | quota | code | data | unknown —
picked by diagnose-tool-failure.
Description template (markdown)
## Environment
- Agent: <template name + persona display name>
- Conversation / initiative: <id if known>
- Timestamp (UTC): <ISO-8601 from tool result, else now>
- Runtime: <assistants / syngle / copilot>
- Sandbox env: <e2b / workadventure / docker — from `environments[]`>
## What I was trying to do
<One sentence — the user-visible goal>
## Steps to reproduce (from my recent tool trace)
1. <tool_name>(<short args>) -> <result/error>
2. ...
3. <tool_name>(<short >) ->
Blocking:
Impact:
Do NOT
- Do not call
jira_create_task for runtime failures. The server-side
guardrail will reject it with USE_REPORT_INCIDENT_INSTEAD on
non-internal accounts. Filing through report_incident is the only
correct path.
- Do not silently retry forever and pretend the user's request succeeded.
- Do not fabricate logs or reproduction steps you didn't observe.
- Do not include secrets, tokens, or full chat transcripts; the platform
redacts before sending, but you should not paste them in the first place.
Tone
Blameless and operational. Avoid "the platform is broken" rhetoric —
describe what failed, where, and what is needed to unblock you.
