Promote Idea to Feature

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

The description explicitly reveals idempotency ('Idempotent — an already-promoted idea returns its existing feature'), which is not declared in the annotations (idempotentHint: false). It also describes the state-changing effects: creates, stamps, links, and returns a feature id, providing substantial behavioral context beyond the annotations.

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 three sentences, each serving a purpose: the first states the core behavior, the second reveals idempotency, and the third provides input guidance and a follow-up pointer. No filler or redundant repetition of annotations.

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 two-parameter tool with no output schema, this description is complete: it covers the operation, the return value (feature id), idempotency, the required parameter origin, and a follow-up step. It leaves little ambiguity about what the tool does and how to invoke it.

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 both parameters with descriptions (100% coverage), so the baseline is 3. The description adds value by pointing to the source of the id ('Resolve the id via list_ideas') and clarifying that only id is required, which is helpful for correct invocation.

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 clearly states 'Promote an idea into a roadmap feature' and elaborates with the exact actions: creates a feature from the idea, stamps the idea 'promoted', links it to the new feature, and returns the feature id. This distinguishes it from sibling tools like create_feature or update_idea.

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?

It provides context on when to use: 'Promote an idea into a roadmap feature' and practical guidance such as resolving the id via list_ideas and only id being required. It also mentions a follow-up action with update_feature. However, it doesn't explicitly contrast with similar tools like create_feature or vote_idea, so it lacks a clear when-not-to-use statement.

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