kingdee_query_stock_in

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful domain behavior: it is query-only, write actions are handled elsewhere, and misusing FCustId instead of FSupplierId on this FormId produces a field-not-found error.

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 purpose is front-loaded and the warnings are clearly separated. The description is somewhat long, but the field-key warning, query-only scope, and filter examples all add actionable value for this domain.

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?

The tool has an output schema, so return values need not be explained. The description provides the missing domain context an agent needs to call it correctly: FormId, supported filters, safe field keys, supplier-field pitfall, and explicit query-only scope.

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 nested QueryInput schema documents the generic parameters, and the description adds substantial domain semantics beyond that: FormId STK_InStock, recommended field_keys, common filter_string examples, and the supplier field-key caveat. It does not explain pagination parameters such as limit and start_row, but those are covered by 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 description names a specific verb and resource (查询采购入库单), gives the exact FormId (STK_InStock), and places it in the inventory-management module. It also distinguishes the tool from write-oriented siblings kingdee_save_bill / kingdee_submit_bills / kingdee_audit_bills by stating it is query-only.

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 clearly says when the tool is used (querying completed/in-transit purchase stock-in bills and supplier information) and explicitly excludes write actions. However, it does not explicitly distinguish this tool from closely named query siblings such as kingdee_query_stock_bills or kingdee_query_bills.

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