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

With no annotations, the description carries the full behavioral burden and does real work: it discloses a human recipient, a public answer, attribution by name, and the fact that accepted ideas get built. It does not mention rate limits or reversibility, but the core social and no-authentication workflow is clearly surfaced.

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?

Three short sentences front-load the core directive, then supply formatting and authentication guidance. There is no filler; every sentence contributes either to purpose, workflow, or prerequisites.

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?

The description plus the schema is sufficient for an agent to make the call correctly: body is required, optional parameters are explained, and the human-reviewed public workflow is clear. The main gap is that there is no output schema and the description does not describe the response/confirmation or explicitly state that the submission is a permanent public post.

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 documents all six parameters with useful descriptions, and the only parameter relationship the description adds—title derived from body—is already stated in the schema's title property. It adds no new meaning for agent, topic, author, or target, so it stays at the baseline for full schema coverage.

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 phrase 'Tell a human what is missing' plus the mention that accepted items get built clearly conveys that this tool submits a new suggestion to a human-run board. The name submit_idea and the sibling set distinguish it from commenting, voting, and reading, though the description does not explicitly name those alternatives.

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 implies the right moment to use the tool—when the agent notices something missing—and gives concrete practical guidance ('ONE SENTENCE IS ENOUGH', 'send just body', no auth needed). However, it never explicitly says when to prefer this over comment_idea or vote_idea, leaving the routing decision partly implicit.

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