failure_analysis

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full load and does so well: it discloses the frozen/deprecated-but-callable status, that nothing is inferred beyond the task's recorded title/result/error/tags, that output specificity is bounded by those fields, and that the combined text is appended to the task as an issue memo readable via task_memo_read. It omits auth/idempotency behavior (e.g. what happens on a repeat call), which keeps it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then frozen status, then routing rule, then artifact breakdown. The three artifact bullets are informative but the entry is longer than strictly necessary; nothing is padding exactly, yet the bullet list could be trimmed without loss.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need not be explained, and the description still covers the three artifact types and the memo side effect. For a two-parameter mutation with no annotations, the main remaining gap is repeat-call/overwrite behavior on the task memo.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both parameters are documented in the schema, so baseline is 3. The description adds that task_id must reference a failed task and that team_id is the owning team, which is useful context but not format or constraint detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Record a failed task as a templated lesson entry') and immediately scopes it to failed tasks. It also names the sibling it is not (diagnose_task_failure) for the adjacent diagnosis use case, so an agent can route without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says the watchdog invokes it automatically once retries stop, and that manual calls are only for a failed task that will not be retried. It names the alternative tool (diagnose_task_failure) and the condition that selects it, leaving nothing to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.