kingdee_query_sales_outstock

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description's added value is the field-key trap: it discloses that FCustomerID is the real key in this environment, quotes the exact error message produced by passing FCustId, and defers to kingdee_get_fields as the authority. That is genuinely useful non-schema context, though return shape and pagination behavior are left to the output schema and parameters.

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 purpose and FormId, then the critical field-key warning, then copy-pasteable examples — a sensible priority order with no filler. Mileage is slightly lost to the multi-line warning block and markdown bold, but each block carries distinct, actionable information.

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 read-only query tool with an output schema, the description covers identity (FormId), filtering, field selection, and the environment-specific field-key pitfall — everything needed to call it correctly. Only the paging behavior (limit max 100, start_row offset) and its relationship to the generic query sibling are unaddressed.

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?

With reported schema description coverage at 0%, the description compensates well: it supplies the concrete form_id value (SAL_OUTSTOCK), shows three working filter_string patterns including the related-field syntax FCustomerID.FNumber='C001', and lists a validated field_keys set. limit, start_row and order_string remain unexplained, but the high-risk parameters are covered.

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 and resource (查询销售出库单/发货单) and pins it to the exact FormId SAL_OUTSTOCK plus the ApiDoc domain, so an agent can identify the entity without opening the schema. It stops short of differentiating from the generic sibling kingdee_query_bills or from kingdee_query_delivery_notice, which would make the boundary unambiguous.

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 clear conditions of use, and the filter_string examples make the intended query scenarios concrete. It never states when NOT to use this tool or which sibling to prefer instead (e.g. the generic kingdee_query_bills), so there is no explicit alternative routing.

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