kingdee_query_bills

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral context beyond that: base-data forms lack an FID column and the tool silently strips FID from fields and sorting, returning a 'notice' field when this degradation occurs (#28). This is exactly the kind of automatic-behavior disclosure an agent needs; only rate limits/field-validation behavior is missing.

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 supported operations, then examples, then the FID caveat, then returns. Each paragraph carries distinct information; only the example list is slightly long relative to its value.

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, so the returns paragraph is partly redundant but still usefully names the has_more/notice fields. Combined with the FID degradation note and form_id examples, an agent has enough to call this correctly; the main remaining gap is routing guidance against the many one-entity query siblings.

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 top-level 'params' wrapper has no description (0% coverage on the counted parameter), but the nested QueryInput properties are fully documented in the schema itself. The description contributes the form_id example values and the FID-removal caveat that affects the field_keys and order_string defaults, but says nothing extra about filter_string syntax or ordering format beyond the schema's example.

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 — query any Kingdee bill list — with the supported operations (filter, sort, pagination) named up front, and the form_id examples make the scope concrete. It implicitly differentiates itself from the many entity-specific siblings (e.g. kingdee_query_purchase_orders) by claiming '任意单据' (any bill), but never names those alternatives explicitly.

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?

The form_id examples (PUR_PurchaseOrder, SAL_SaleOrder, STK_InStock, plus base-data forms like BD_Currency) implicitly tell the agent what this tool is good for. However, there is no explicit statement about when to prefer this generic tool over the dozens of specialized query siblings, nor any prerequisites or exclusion criteria.

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