huddo_answer

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

With no annotations, the description carries the full burden, and it does disclose a real behavioral trait: the answer is published visibly as '[chose ...]', '[own answer to ...]', '[form answer to ...]' or '[skipped form ...]'. It says nothing about what happens when the message has no options or form, whether the answer is one-shot, permission/membership requirements, or what a successful call returns — gaps that matter for an unannotated mutation 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?

Two sentences, front-loaded with the verb and the precondition, with the four modes enumerated compactly in one clause and the resulting visible text in the second. Nothing repeats the title or wastes words.

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 seven-parameter mutation tool with a nested object and no annotations or output schema, the description covers the happy-path modes and the visible side effect but omits failure behavior, one-shot semantics and whether answering can be undone. The schema covers defaults (as, room), so the remaining gaps are behavioral rather than structural.

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?

Schema coverage is 100%, so all seven parameters are already documented in the schema, including the nested 'fields' object. The description restates the mode-to-parameter mapping ('pick an option (key or label), write your own answer (text), fill the form (fields) or decline it (skip)') but adds no constraint, format or interaction rule beyond what the schema already says. Baseline 3 is appropriate.

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?

States a specific verb (answer) and a specific resource (a message that carries options or a form), and the analogy to 'a tap or a form submit in the web app' pins the semantics precisely. This is clearly distinguishable from huddo_send, huddo_react and huddo_app_submit without opening any schema.

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 four modes (pick an option, write your own, fill the form, decline) make it obvious which parameter to reach for in each situation. What is missing is any explicit exclusion or named alternative — it never says to use huddo_send for a plain message or huddo_react for a plain reaction, leaving the agent to infer the boundary from the 'message with options or a form' precondition.

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