mkt_retro_analyze

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

With no annotations, the description must carry the behavioral load. It does contribute two real facts — the operation is read-only ("只读") and the metric definitions are human-pinned rather than inferred by the tool — but says nothing about how much it reads from the path, runtime, side effects, or what the analysis returns.

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?

Two short sentences, front-loaded, with no filler — structurally efficient. But the compression goes too far: "日志里被反复提到的那几句话" is elliptical to the point of being unactionable for an agent that has no idea what log or which phrases.

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 tool with a nested-object parameter, a required path and no output schema, the description should say what the analysis produces and how the inputs shape it. It never explains what comes back, what path must point at, or what max_files guards against, so an agent would have to guess before calling.

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 coverage is only 33%: "path" has no description at all, leaving it ambiguous whether it is a directory, a file, or a glob — a serious gap for the one required parameter. "口径仍由人钉" does usefully explain the role of the optional "facts" object, but "max_files" (default 20000) is never explained, so the description compensates only partially.

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?

It names a verb+resource ("只读复盘分析") and enumerates the analysis targets (channel ledger, waste, conflicts, recurring log lines), which gives a rough sense of scope. But the enumeration is impressionistic and nothing distinguishes it from the very close sibling mkt_retro_scan, nor from mkt_ledger_query / mkt_audit which cover overlapping ground.

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?

There is no when-to-use statement and no named alternative, despite mkt_retro_scan sitting right next to it in the sibling list with a nearly identical name. The only guidance-adjacent content is "口径仍由人钉", which tells the agent the human pins metric definitions but not when to invoke this tool.

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