Request a feature

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

Annotations already convey that this is not read-only (readOnlyHint: false), not idempotent (idempotentHint: false), and not destructive (destructiveHint: false). The description adds the behavioral context that the request is 'free, no credits' and that 'the use case is what gets built,' which suggests the request has real-world impact on Hermoso's roadmap. However, it does not disclose what happens after submission (e.g., whether a confirmation is returned, how long it takes, or whether multiple submissions are allowed), which leaves some behavioral ambiguity.

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 compact (about 60 words) and front-loaded with the primary action. The first sentence states the tool's purpose, the second provides usage conditions and examples, and the third gives content guidance. Every sentence adds value: the 'Free, no credits' is a key differentiator, and the instruction on including the use case is critical for effective feature requests. There is no redundant phrasing or filler.

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 whose sole function is to submit a feature request, the description covers the essential context: what it does, when to use it, and how to structure the request. With no output schema required, there is no need to describe return values. Annotations (openWorldHint: true) indicate external effects, and the sibling set clearly positions this tool as distinct from others like 'report_bug' and 'hermoso_capabilities.' Thus, the description is complete for an agent to call it correctly.

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 thorough descriptions for both 'summary' and 'details' (schema coverage 100%). The description goes beyond this by reinforcing the importance of the use case over the feature name, explicitly instructing 'Say what the user was trying to achieve, not just the feature name.' It also echoes the details parameter's guidance, which helps the agent prioritize the content of the request. While it does not add new parameter-level details, it adds a strategic lens on how to fill them, thus improving parameter semantics.

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 clear verb and resource: 'Ask the Hermoso team for a capability that doesn't exist yet.' It then enumerates concrete examples (unsupported platform or channel, missing model, export format) and distinguishes itself from the sibling 'report_bug' by focusing on requests for new capabilities rather than defect reports. The statement 'Free, no credits' further clarifies its unique purpose among the large sibling set.

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 explicitly states 'Use this when you need something Hermoso genuinely can't do' and lists scenarios, which is strong usage guidance. It implicitly differentiates from 'report_bug' (which handles defects) but never names it directly. It also implies not to use it for existing capabilities, though an explicit 'when not to use' is absent. The guidance to 'Say what the user was trying to achieve' provides clear direction on framing the request.

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