submit_punch_review

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

With no annotations, the description fully discloses behavioral traits: side effects (auto book marking on pass, issue tracking, status resets on reopen), action constraints (only three values allowed), and interaction with other tools (upsert_punch_day for re-upload). It does not mention authorization or rate limits but covers critical behaviour well.

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 well-structured with bullet points for actions and parameters, front-loaded with the main purpose. Every sentence adds value, and the length is appropriate given the complexity. There is no redundancy 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?

Given the complexity, lack of schema descriptions, and no annotations, the description is remarkably complete. It covers purpose, all parameters with semantics, side effects, workflow context (e.g., major changes require other tools), and even hints at the return value ({ok, review}). The presence of an output schema does not detract from the description's completeness.

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 has 0% description coverage, so the description compensates fully. It explains each parameter: book_id (string), day (integer starting at 1), action (enum with three values), and issues (array required for issue action, with subfields module, seq, kind, note). It also clarifies the meaning and constraints of each action value.

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 purpose: submitting human eye review conclusions for a specific day, with three distinct actions (pass, issue, reopen) and their consequences. It distinguishes the tool from siblings by focusing on the punch day review closure, and references related tools (upsert_punch_day) for different workflow steps.

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 provides explicit context for each action (e.g., what happens on pass, issue, reopen) and notes that major changes should not be handled with this tool but via other processes. However, it does not explicitly compare to sibling tools like submit_review, leaving some ambiguity about when to use this versus related tools.

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