add_chapter_review

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

With no annotations, the description carries the full behavioral burden. It does disclose one genuinely useful behavioral trait: 'content 前自动加 🌕 署名' (🌕 attribution is automatically prepended to content), which prevents the agent from duplicating the prefix. However, for a mutation tool it says nothing about auth requirements, idempotency, duplicate handling, or side effects beyond the prefix behavior.

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 compact sentence with zero filler. The most decision-relevant information (chapter-level scope, no citation, auto-attribution) is front-loaded, and every clause earns its place.

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?

Has an output schema, so return-value documentation is covered. For a simple three-string-parameter create tool, the description is mostly adequate: scope and auto-prefix behavior are disclosed. However, it omits operational details an agent might need, such as whether the chapter must belong to the given book_id or any content constraints, leaving minor gaps for a simple mutation tool.

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 description coverage is 0%, so the description must compensate, but it only indirectly illuminates the content parameter via the auto-prefix note and the chapter-scope context. It adds no meaning for book_id, chapter_uid, or their relationship (e.g., that the chapter must belong to the book). The parameter names are self-evident, but the description fails to bridge the 0% schema coverage gap.

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 identifies a specific action: adding a chapter-level thought/review attached to the whole chapter with no original-text citation. This distinguishes it from sibling review tools like add_review and add_comment. It stops short of 5 because it never states the verb+resource directly (e.g., 'adds a review to a chapter') and relies on characteristic descriptions rather than an explicit statement of what the tool does.

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?

Usage context is implied through the parenthetical '挂在整章上，无原文引用' (attached to the whole chapter, no original text citation), which signals when this tool is appropriate versus a citation-based or book-level review. However, no alternatives are named and there is no explicit when-to-use/when-not-to-use guidance, leaving routing decisions to inference.

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