plot_forecast

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

With no annotations provided, the description carries the full transparency burden. It meaningfully discloses that the tool only plots rather than predicts, describes the five unified preprocessing steps via _common._prepare_series, mentions interpolation/aggregation/timezone reporting, and documents inline_data versioning and limits. It stops short of describing the actual return format or any side effects, but the core behavior is transparent.

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 compact and front-loads the key distinction (plotting vs forecasting) and the core output (raw line + 7-day MA). Some references like '工具 24' and '_common._prepare_series' are cryptic but not redundant; overall it earns its length without fluff.

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?

The description covers purpose, data source options, preprocessing behavior, and inline data formats, which is substantial for a plotting tool. Yet with no output schema or annotations, it does not explain what the tool returns (e.g., image path or rendered figure), what happens if neither file_path nor inline_data is provided, or how errors surface. These are meaningful gaps for an agent selecting and invoking the 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%, so the description must compensate. It does add real semantics for inline_data: supported shapes (records array or header/rows object), mutual exclusivity with file_path, and a pointer to limits in SPEC.md. However, date_col, value_col, and file_path are left to inference from their names, and no required-combination guidance is given.

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 action and resource: plotting a time-series line chart with raw values plus a 7-day moving average. It also explicitly sharpens the boundary by saying '仅作图不预测' and referencing the forecasting tool, distinguishing it from time_series_forecast and sibling plot tools.

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 explicitly tells agents not to use this tool for forecasting ('预测见工具 17') and clarifies that inline_data and file_path are mutually exclusive alternatives. However, it does not explicitly contrast this tool with other plot siblings like plot_scatter or plot_histogram, so usage guidance is strong but not comprehensive.

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