kingdee_cancel_bills

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

Goes well beyond the annotations: names the actual endpoint used (standalone CancelAssign, no opNumber), the fallback path (ExecuteOperation + top-level opNumber when operation is overridden), and the payload shape ({"Ids":"1,2,3"}). Annotations already cover safety profile (destructiveHint=false, idempotentHint=false), and nothing in the text contradicts them, though batch partial-failure behavior is unstated.

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?

Purpose and parameters are front-loaded, but a large share of the text is provenance meta-commentary ('范探源 2026-08-07 三重证据查证', '反编译', 'QA 严过关…真机验证 B→D 成功') that does not help an agent decide or invoke. The 'old docs said Cancel, don't cite it' note addresses a document the agent does not have.

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?

Output schema exists, so return values need not be described, and the tool's core invocation contract (form scope, id/number targeting, endpoint, override) is covered. Missing pieces are permission requirements, multi-bill partial-success semantics, and any note on irreversibility — relevant for a state-rollback mutation.

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?

Outer schema coverage is effectively 0% (a single opaque 'params' wrapper), so the description must compensate — and it does: bill_ids as FID list with priority, bill_nos as FBillNo fallback, the at-least-one rule, and when operation must be supplied explicitly. It adds real semantics beyond the nested schema, though it does not elaborate on form_id beyond examples already in the 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 opening states a specific verb and resource ('撤销单据或基础资料'), scopes the operation to draft/in-approval state rollback, and pins the concrete action (CancelAssign) and generic FormId scope. It is distinguishable from most siblings conceptually, though the description never names void/close/delete explicitly as different operations.

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 a state precondition ('草稿/审批中状态回退') and a parameter rule (bill_ids or bill_nos, at least one), plus an override path for 二开 forms. But with siblings kingdee_void_bills, kingdee_close_bill, kingdee_delete_bills, kingdee_forbid_bills all being state-changing actions on the same FormId, the description never says when to pick cancel versus those alternatives.

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