report_issue

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

With no annotations, the description fully discloses the behavioral contract: it blocks for minutes, always returns eventually, warns about double-filing on retry, explains pending:true and job_id behavior, covers fallback to a prefilled URL, and describes what outputs to surface (agent_message/upgrade advice). This goes far beyond a typical description and the absence of annotations makes this transparency essential.

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 long but every sentence carries critical operational detail: timing, retry dangers, fallback paths, and versioning. It is front-loaded with the core purpose and then systematically covers behavioral nuances. While it could be tightened, the length is justified given the tool's complexity and the high stakes of misuse (double-filing).

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?

Even without an output schema, the description explains all possible return scenarios: triage result, pending flag, job_id, prefilled URL, and agent message. It also covers edge cases like unreachable worker and third-party repos. For a tool with this many parameters and complex asynchronous behavior, the description is exceptionally 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?

The schema already covers all 7 parameters with 100% coverage, so the baseline is 3. The description adds valuable semantic context by insisting on passing mcp_version and panel_version from the environment, detailing the body's required contents (exact error text, frontend version), and clarifying repo choices. This extra guidance elevates it to a 4.

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 action: 'File or triage a GitHub issue for a bug/problem you hit', naming the resource (GitHub issue) and distinguishing it from all sibling tools (none are issue-related). It further details the triage behavior for our repos versus third-party repos, making the purpose unmistakable.

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 clearly explains when to use the tool (for bugs/problems in ComfyUI ecosystems) and gives detailed scenario-specific guidance: for our repos it uses the AI triage worker, for third-party repos it returns a shareable URL. It also provides strong operational guidance like 'ALWAYS pass mcp_version and panel_version' and warns against blind retries. It does not explicitly mention alternative tools, but the context is strong enough for an agent to decide.

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