read_text

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

With no annotations, the description carries the full burden and does fairly well: it discloses the line-oriented read model, that offset is 1-based, that limit caps returned lines, that total_lines is returned for pagination, and that binary input is rejected. It omits encoding assumptions, file-size limits, and error behavior on missing paths, but the core operational traits are present.

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?

Three compact clauses, front-loaded with the core action and then the parameter semantics, with zero filler. The Chinese phrasing packs the format list, pagination contract, and rejection rule into minimal space.

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?

An output schema exists, so the description is not obligated to document return values, and the parameters are covered. The remaining gap is the absence of any tie-breaker against read_xml and no note on encoding or size limits, which an agent handling large or non-UTF-8 files would want.

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, and it does for the two non-obvious parameters: offset is defined as a 1-based line number (critical, since the default of 1 could otherwise be misread) and limit as the maximum number of lines. Only 'path' is left unexplained, which is self-evident from the required-parameter schema.

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 states a specific verb and resource ('按行读取一个文本文件') and enumerates supported formats (xml/lua/txt/csv), so an agent immediately knows what this does. However, it never distinguishes itself from the sibling read_xml, which it even lists as a supported type, leaving a real routing ambiguity unresolved.

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 is implied rather than stated: no explicit 'use this when' or 'use read_xml instead when' guidance is given, despite read_xml being an obvious alternative for part of this tool's format coverage. The one hard rule provided — that binary files are rejected — is a useful negative constraint but is really a behavioral trait, not selection guidance.

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