读取飞书电子表格

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses that it returns CSV text by default, that detail=cells exposes formulas/styles/comments, that omitting sheet params yields a sheet list, and that large tables may be truncated (the truncation note is in the schema but the description reinforces it). The read-only nature is implied by '读取'. This level of behavioral detail exceeds what a typical tool description provides.

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 a single, dense sentence that front-loads the core purpose and then quickly covers the key behavioral branches. There is no redundant wording; every clause adds information. The structure is efficient and scannable.

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 six parameters, no output schema, and no annotations, the description is remarkably complete. It covers the main use cases, the two modes, the detail option, and the truncation caveat. It does not explicitly mention authentication or error handling, but those are typically implied for read tools and not essential for correct invocation. For a read tool, this description provides all the context an agent needs to call it 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?

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the interplay between sheet_name/sheet_id and the list mode, and by stating the default behavior of range and detail. While some of this is also in the schema (e.g., '都不传时返回子表清单'), the description synthesizes the parameter logic into a coherent flow, which helps an agent understand how the parameters interact rather than just their individual meanings.

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 reads a Feishu spreadsheet (电子表格), explicitly distinguishing it from multidimensional tables (不是多维表格). It also differentiates from sibling tools by specifying the two operational modes: returning a sheet list when no sheet is given, or reading a region when a sheet is provided. The verb '读取' (read) plus the resource '电子表格' makes the purpose unambiguous.

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 gives explicit conditional guidance: '不传 sheet_name/sheet_id 时返回工作簿的子表清单；传入子表后按区域读取' (without sheet params, return the sheet list; with a sheet, read by region). It also clarifies the detail parameter options and the default CSV output. While it doesn't explicitly name alternative tools like read_feishu_base_records, it clearly delimits its scope by stating it is not for multidimensional tables, which effectively routes agents to the correct sibling. This is strong usage guidance.

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