submit_review

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

With no annotations provided, the description fully carries the burden of behavioral disclosure. It details side effects (marks session as done), computational behavior (parent_msg generated on-demand, not stored), filtering (internal words filtered out), how portrait_delta is computed and appended, and idempotency (repeated submission overwrites with previous in prev_json).

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-organized with a summary first line, then bullet points for key behaviors, and a parameter list. It uses emojis for emphasis. Slightly verbose in places but generally efficient 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?

Given the tool's complexity (4 parameters, 2 required, no schema descriptions, no annotations, but output schema exists), the description covers purpose, parameters, behavioral details, return structure, and side effects. It is appropriately complete for an AI agent to use correctly.

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 input schema has 0% coverage (no descriptions), but the description compensates thoroughly. It explains session_id as 场次 id, item_results as an array with nested structure including fields like question_id, seg, seq, result (with allowed values: 对|错|卡), and cause (枚举: 计算|概念辨析|策略|其他). teacher_note and parent_msg_override are also explained with context.

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: '课后回收' (after-class review) to record per-question correctness, generate parent feedback, and update student portrait. It specifies the return structure and distinguishes itself from siblings like 'submit_punch_review' by focusing on session review rather than punch 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?

The description does not explicitly state when to use this tool versus alternatives. It mentions that submission marks the session as done, but provides no guidance on when to use submit_review vs. other feedback-related tools like upsert_feedback_sheet or get_feedback_sheet.

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