AI Analysis

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

Annotations already declare readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds nothing about which of the eight actions actually mutate state, what `autoApply` does, or that these are non-deterministic AI calls with latency/cost implications — a meaningful gap for a non-idempotent multi-operation tool.

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?

Two sentences, front-loaded with the capability list, no filler. The enumeration largely restates the action enum rather than adding meaning, but it is short enough that the cost is low.

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?

For a 21-parameter, nested-object, eight-action dispatcher with no output schema, the description should map parameters to actions and flag which operations write. Instead it gives a one-line capability list, leaving an agent unable to construct a valid call without reverse-engineering the schema.

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 only 5%: 20 of 21 parameters, including nested `config`, `thresholds`, `relationConfig` and several issue-array shapes, are undocumented anywhere. The description only points at the `action` field and loosely implies that enrich/triage/label operations exist, without saying which of `issueId`, `issueIds`, `projectId`, `existingLabels` or `autoApply` belongs to which action.

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 family and resource (AI analysis over issues) and enumerates the concrete capabilities: enrichment, triage, label suggestion, duplicate detection, related issues. That maps well onto the action enum, though 'schedule triaging' is ambiguous versus `triage_all`, `enrich_issue_sections` is never mentioned, and nothing distinguishes it from siblings like `ai_plan` or `ai_generate`.

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 capability list implies which `action` value to pick for a given task, and the final sentence makes the dispatch mechanism explicit. But there is no guidance on when to prefer this over `ai_plan`/`ai_generate`, no prerequisites, and no statement of which actions have side effects.

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