qianji_preview

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so 不发写请求 largely restates structured data and earns no credit. The genuinely additive piece is that preview is not a mandatory manual-approval step, which is one real workflow disclosure but nothing about validation failure modes or what a preview 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?

A single compact sentence (two clauses joined by a semicolon), with the core purpose front-loaded and the optionality caveat appended. Nothing is padded or repeated.

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 return values need not be described, and annotations cover the safety profile. But for a tool whose command spans dozens of actions and a large nested schema, the description is thin: it omits how validation errors surface, what 'balance impact' means concretely, and any link to the execute sibling.

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?

There is a single top-level command parameter with 0% schema description coverage at that level, though the nested Command object carries its own field descriptions (fee, time, amount, object_id, etc.). The description only hints at 'commands and references' and adds no meaning about the command structure or the 50+ action enum, so it fails to compensate for the coverage gap.

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 gives a specific verb pair (校验/预览 = validate/preview) plus resources (指令与引用, 余额影响), and rules itself out of the write path with 不发写请求, which implicitly distinguishes it from qianji_execute. It is clear but never names the write sibling explicitly.

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 note 预览不是强制人工审批 clarifies that using preview is optional and not a mandatory approval gate, which is useful workflow context. However it never states the positive when-to-use case (e.g. run before qianji_execute) nor any exclusions, leaving usage implied.

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