biz_query_sales

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

With no annotations, the description carries the burden and does well: it states the hard constraint '禁止拼接 SQL', explains that gmv_cent is in cents and must be divided by 100, and clarifies which ID sources are valid. It does not cover date-range defaults or pagination behavior, but the disclosed constraints and unit handling are substantial.

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 description is scannable and organized into labeled sections, with the core purpose first followed by constraints, ID guidance, and routing rules. Every section communicates a distinct operational fact, and there is no filler or redundant restating 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?

For a tool with 8 optional parameters rate and an output schema present, the description covers purpose, usage boundaries, ID namespaces, grouping options, and unit conversion. It stops short of specifying date formats and category values, which are relevant to correct invocation, so it is not fully complete.

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?

Schema description coverage is 0%, so the description must compensate. It explains group_by allowed values, shop_id formats, channel_id values, and sku_id sourcing. However, it does not clarify date format for start_date/end_date, valid category values, or limit semantics, leaving meaningful gaps for an agent invoking the tool.

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 opens with a clear verb and resource: '按结构化过滤汇总 GMV / 订单 / 退款率' (aggregate GMV/orders/refund rate by structured filters). It further differentiates itself from siblings by explicitly stating when to use biz_anomaly_scan or biz_get_order instead, so an agent can reliably select it.

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 provides explicit '【何时用】' examples and '【何时不用】' alternatives, naming sibling tools. It also gives hard constraints like prohibiting raw SQL and instructing where to source IDs, which tells the agent not only when but how to use the tool correctly.

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