qianji_execute

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

With annotations already declaring destructiveHint=true, idempotentHint=true, and readOnlyHint=false, the description still adds valuable behavioral context: user authorization is required, idempotency is achieved through a stable request ID, and post-success native read-back verification is mandatory. It does not detail what side effects occur or how failures are surfaced.

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 front-loaded sentence separated by semicolons. Every clause carries operational meaning: authorization, idempotency, and verification. There is no filler.

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 destructive execution tool with a 50+ action command schema, the description covers key workflow constraints (authorization, idempotency, read-back verification) and the output schema handles return values. However, it omits sibling routing guidance such as using preview before execution or operation_status afterward, which matters for safe invocation.

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 reported as 0%, so the description must compensate, but it only explains request_id semantics ('稳定请求编号防重复'). The command parameter and its large action enum are not described at all, leaving the agent to rely entirely on the nested schema.

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 verb and resource: '执行...记账指令' (execute bookkeeping commands). It is clearly a mutation/execution tool rather than a query or preview, but it never names or distinguishes itself from siblings like qianji_preview or qianji_query.

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 gives clear usage context: commands must already be user-authorized, a stable request_id prevents duplicates, and success must be verified via native read-back. It does not state when not to use this tool or explicitly route agents to qianji_preview/qianji_operation_status before or after execution.

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