Reads the full text of a downloaded chapter by item_id or 1-based index from a book's local chapter list. Use item_id for reliable lookup because index follows online catalog order.
按 item_id 或本地可用章节列表的 1-based index 读取正文；index 按在线目录排序，与下载目录位置不同，推荐 item_id。
| Name | Required | Description | Default |
|---|---|---|---|
| index | No | 章节序号，从 1 开始 | |
| book_id | Yes | 数字书籍 ID | |
| item_id | No | 章节 item_id；与 index 二选一 | |
| max_chars | No | 0 表示返回完整正文 |
Changes observed during successful MCP inspections.
v0.3.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden; it usefully discloses a non-obvious ordering gotcha for the index selector. It does not state what happens if the requested chapter is not locally available (error vs fallback), nor anything about the truncation behavior governed by max_chars, both of which affect a caller's decision.
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 dense sentence front-loads the two selection modes, then immediately delivers the ordering caveat and the recommendation. Every clause carries operational value and nothing is padding.
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 four-parameter read tool with no annotations and no output schema, the definition covers identification and ordering well but leaves gaps on failure modes (missing local chapter), on how max_chars interacts with the returned body, and on how it differs from the sibling readers. Adequate but not complete.
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 the baseline is 3, but the description adds genuine meaning beyond the schema: it clarifies that index enumerates the locally available list in online-catalog order (not download order) and that item_id is the preferred selector. That is exactly the disambiguation an agent needs when both optional selectors exist.
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 names a specific verb and resource ('读取正文' – read chapter body) plus the two ways to identify the chapter (item_id or 1-based index into the locally available chapter list). It implicitly separates this tool from the plural/latest siblings by constraining the index to the downloaded-chapter list, but it never names tnd_read_downloaded_chapters or tnd_read_latest_chapter, so an agent must infer which reader to pick.
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?
It gives parameter-level guidance ('推荐 item_id' – item_id is recommended) and warns that the index follows online-catalog order rather than download-directory position. It does not say when to choose this tool over the sibling readers (latest chapter, plural chapters) or what precondition must hold (the chapter must already be downloaded).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.