kb_read_section

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

No annotations are provided, so the description carries the behavioral disclosure burden. It discloses the required precondition, the valid input source, and the failure mode for invalid section_id values. It could additionally state read-only behavior or max_chars truncation, but '读' plus the output schema cover the most important behavioral expectations.

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 two compact labeled paragraphs, front-loading the purpose before the critical usage constraints. Every sentence adds information about prerequisites, valid inputs, or failure modes, with no 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 no annotations and a 4-parameter schema, the description is nearly complete: it provides workflow step, prerequisite, parameter semantics, and failure behavior, while the output schema covers return shape. The only minor omission is explicit max_chars truncation behavior, which is a small gap for a read-a-section 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%, and the description compensates by explaining the two ambiguous parameters: section_id must come from the same outline, and offset can be taken from sections[i].offset. doc_id is self-evident from its name and required status, and max_chars is self-explanatory, though it is not explicitly described.

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 opens with '第 2 步·读某一章' and states '按 section_id 或 outline 返回的 offset 读取一节', giving a specific verb (read), resource (one section), and input modes. It differentiates from the sibling tools by naming kb_get_outline as its required precursor and by focusing on a section rather than the whole document or outline.

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 explicitly says '必须先调 kb_get_outline', restricts section_id to 'from the same outline's sections[i].section_id', allows passing sections[i].offset as offset, and warns that cross-document section_id will fail. This provides clear when-to-use and when-not-to-use guidance with no ambiguity.

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