triage_release_blocker

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

With no annotations, the description carries the full burden. It clearly describes the return payload (likely_cause, evidence_summary, etc.) and input flexibility, which is helpful. However, it does not disclose potential side effects, read-only guarantees, error cases, or permissions needed for a tool that analyzes release blockers.

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?

The description is exceptionally concise: two sentences that front-load the purpose, then cover input requirements and output contents. Every sentence adds meaningful information with no wasted words.

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?

Given the absence of an output schema, annotations, and schema descriptions, the description does a reasonable job of conveying the tool's core contract. But it omits the generate_remediation parameter, fails to explain edge cases like invalid or multiple IDs, and does not situate this tool relative to siblings such as run_release_check or get_release_context. It is adequate but not fully complete.

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 0%, so the description must compensate. It lists five of six parameters and correctly states that at least one identifier is required, which contradicts the schema's optional-looking defaults. However, it omits generate_remediation entirely and gives no semantic detail about what each ID references or how they relate, leaving the agent with only names.

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?

The description opens with a specific verb and resource: 'Root-cause evidence + next actions for a release blocker.' It clearly distinguishes this tool from sibling tools like run_release_check or get_release_context by focusing on triage and root-cause analysis, and it further defines the output type (BlockerTriage).

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?

The description provides clear context: use this when you need root-cause evidence and next actions for a release blocker. It also lists acceptable identifier types and notes the 'at least one required' constraint. However, it does not explicitly compare against alternatives or state when NOT to use it.

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