kingdee_create_lx_billing

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

Annotations already declare readOnly=false, destructive=false, idempotent=false, openWorld=false, so the safety profile is covered; the description adds real value on top by disclosing the four-step pipeline, the non-obvious constraint that WebAPI push drops business fields for these bill types, the is_delete_entry=false trick that preserves _LK linkage, and the fail-fast contract (halt + halted_at + recovery_hint). It does not spell out permission requirements or that repeated calls create duplicate bills despite idempotentHint=false.

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?

Front-loaded with the one-line summary, then background, then a numbered workflow, then the return contract — each block earns its place and the failure behavior is not buried. No filler or repetition of the schema.

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 4-step mutation an agent has what it needs: preconditions (source bill type per kind), the pipeline stages, partial-failure semantics, and a return contract that overlaps the existing output schema rather than replacing it. The remaining gap is the wrapper 'params' envelope and any auth/rule prerequisites (enable_default_rule / rule_id implications).

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?

The description enumerates several business fields it will write (amount / material / qty / so_no) and ties them to the save step, which is useful orientation. However the top-level schema exposes a single undocumented 'params' wrapper (0% coverage), and the description never explains that all inputs are nested under 'params' or how kind selects which optional fields apply — the agent must read the nested $defs to learn the receipt-vs-payment field split.

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 first line names the exact resources (TRNV_Receipt / TRNV_PaymentSlip) and the exact composite operation (push → save → submit → audit), which is far more specific than a generic 'create bill'. The background section explains why this exists versus plain push, but it never names the sibling alternatives (kingdee_push_bill, kingdee_push_and_audit, kingdee_create_and_audit) it overlaps with, so the differentiation is inferred rather than stated.

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 context for when this is the right tool: 二开收/付款单 destined for 账套初始化 / 在途收付款数据, where a bare push would leave 金额/物料/SONo empty. The auto_audit=False case is explicitly framed as the '导入后人工核对' scenario. Missing are explicit exclusions or a pointer to the generic push/create-and-audit tools for non-二开 bill types.

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