kingdee_upload_attachment

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

Beyond the annotations (readOnly=false, idempotent=false, destructive=false), it discloses the chunking protocol, the 4 MiB per-block ceiling, the file_id continuation contract, that upload does not trigger submit or audit, and the success=true/next_action=null completion signal. The no-retry caveat on failure is exactly the kind of non-obvious behavior an agent needs.

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 action, then descending specificity: transport mode, size limit, multi-chunk ordering rule, side-effect boundary, and completion/retry semantics. Every sentence carries a distinct constraint; no filler or repetition of the tool name.

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, yet the description still supplies the one piece of result interpretation an agent needs — success=true with next_action=null means fully complete. Combined with the mutation semantics and chunk-ordering rules, nothing needed to call it correctly is missing.

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 single top-level parameter has 0% documented coverage, but the nested schema properties are richly described, and the description adds protocol-level meaning the schema cannot: send_byte is the current Base64 chunk (≤4 MiB decoded), file_id is the returned id from the first block and is required for continuation, and is_last is true only on the final block. Fields like entry_key, alias_file_name, and bill_no are left to the schema, so it is not exhaustive.

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?

States a specific verb (upload), resource (an attachment block), and target (binds to an existing bill header or entry line), plus the protocol it follows (WebAPI V6.0). It is clearly distinguishable from kingdee_download_attachment and from the bill-mutation siblings without opening the schema.

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?

Gives concrete operational guidance: bills must already exist, Base64 is passed directly rather than read from server disk, chunks must be sent in order with a consistent bill/entry/filename, and only the final block sets is_last=true. It also warns not to auto-retry after failure or an unknown result. It does not explicitly name alternative tools (e.g. download_attachment) or exclusion cases, which keeps it below a 5.

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