fast_calc_reports

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

With no annotations, the description carries the full burden and does so richly: it discloses the ~50–60KB output size, the 50KB truncation failure mode, the complete:true sentinel for self-checking, the verbatim-number requirement (禁止自行换算), and the IRR-non-convergence caveat. These are behavioral traits beyond anything the schema 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?

Dense but front-loaded: purpose first, then output structure, then truncation/batching, then numeric-integrity rules. Every clause carries operational information, though the length is heavy and some output-structure detail could be trimmed.

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 complex financial-modeling tool with nested inputs, no output schema, and no annotations, the description supplies the output shape (_meta.years, financial_ratios row list, annual matrices), truncation handling, and result-interpretation guidance. Nothing essential to correct invocation is missing.

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 already 100%, so baseline is 3, but the description adds real value by explaining WHY tables exists (truncation avoidance / 省流且截断自检) and reinforcing the comma-separated, .txt-optional format and the complete flag. It goes beyond restating the schema's parameter text.

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?

States a specific verb and resource with scope: 5类输入txt → 16键JSON（11张报表+指标+IRR/MIRR诊断+资金缺口）. An agent can tell this apart from siblings like fast_calc_excel and fast_calc_solve without opening a schema, because the exact output composition is enumerated.

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?

Gives clear conditional guidance: if the client 50KB response limit truncates the payload, pass tables="..." to pull in batches. It also directs the agent to trust annual IRR and corrected MIRR when irr_health/warnings flag non-convergence. It does not, however, explicitly contrast itself with the sibling fast_calc_excel/fast_calc_solve tools.

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