gui_answer_card

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

The description clearly indicates the tool answers the current card with an ease button, which is a straightforward action. However, it omits details about side effects (e.g., scheduling changes), error conditions, or return value structure. With no annotations, the description carries the full burden and provides adequate but not complete transparency.

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?

A single, well-structured sentence conveys all necessary information without redundancy. Every word is essential and front-loaded.

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 simple action, the description covers the primary behavior. However, it lacks context about the review state (e.g., must be called after 'gui_show_question' and before 'gui_show_answer'?) and does not reference the output schema or possible errors. Given the tool's simplicity and the presence of an output schema, completeness is adequate but not comprehensive.

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 parameter 'ease' is explained in the description with explicit mapping (1=Again, 2=Hard, 3=Good, 4=Easy). This compensates for the lack of schema description and enum constraints, providing clear meaning beyond the raw integer type.

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 the tool's function: 'Answer the current reviewer card with an ease button'. The mapping of ease values (1=Again, 2=Hard, 3=Good, 4=Easy) adds specificity, and the tool is well-distinguished from sibling 'answer_cards' (which likely addresses multiple cards).

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?

No explicit guidance on when to use this tool versus alternatives like 'answer_cards' or 'gui_show_answer'. The description implies it's for a single card in review, but does not state prerequisites (e.g., must be in review mode) or when not to use it.

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