report_bug

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

With no annotations provided, the description carries the full burden of disclosing behavior. It states that account identity is attached automatically, that replies arrive in the user's FLUF inbox, and that the agent should inform the user after filing. This conveys the effect of the action and expected workflow. While it does not cover system-level details like rate limits or confirmation mechanics, it provides solid context for a support-ticket 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?

Although the description is longer than average, every sentence earns its place: purpose, two trigger situations, exclusion criteria, procedural instruction, and inbox expectation are all essential. It is front-loaded with the core action and organized with numbered points, making it easy to scan and apply.

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 tool with no output schema and moderate complexity, the description is complete: it explains why the tool exists, when to invoke it, what to avoid, what happens after filing, and how replies are delivered. Sibling tools are clearly different, and no critical usage context is missing.

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 input schema already provides 100% coverage of all four parameters with descriptive text for each. The description does not add parameter-specific meaning, but it does indirectly inform severity selection by distinguishing reportable bugs from user-fixable issues. This meets the baseline for schema-covered parameters without needing compensation.

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 'Raise a bug with FLUF support,' a specific verb+resource that clearly defines the tool's purpose. It further distinguishes from siblings by detailing two precise situations (user-reported and self-encountered issues) that no other listed tool addresses. This goes well beyond a mere statement of function.

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 offers explicit when-to-use guidance via two enumerated scenarios, and equally explicit when-not-to-use exclusions (expired token, lapsed plan, reauthorisation). It also instructs the agent to tell the user after filing and to skip asking for identity, making the call criteria unambiguous.

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