sw_generate

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

With no annotations provided, the description carries the full disclosure burden. It reveals that the tool does not return data, that auto_decided lists user decisions to relay, that workers may run parallel with different seeds, and quantifies the collect_ssb performance tradeoff. This is far beyond a minimal statement.

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 long but every section serves a purpose: usage modes, prereg binding, workers behavior, and collect_ssb tradeoff. It is structured with clear headings and bolded warnings, making it scannable despite the detail.

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 description thoroughly covers core behavior, performance implications, and user-facing output, and the output schema exists to explain return values. However, it omits descriptions for three parameters (preset, overrides, num_samples) and does not state what happens if neither draft_id nor intent is provided. This leaves minor gaps for a tool of this complexity.

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 coverage is 0%, so the description must compensate. It meaningfully explains draft_id, intent, prereg_id, workers, and collect_ssb, but leaves preset, overrides, and num_samples completely unexplained. It adds significant value for most parameters but is incomplete for the full parameter set.

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 '生成信道数据集，返回句柄与统计摘要（不返回数据本身）', clearly stating the action (generate), the resource (channel dataset), and the return type (handle + stats, not data). This distinguishes it from sibling tools like sw_describe_dataset or sw_validate.

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?

Explicitly explains two usage modes ('协商过：只传 draft_id' and '用户说"随便，默认就行"：直接传 intent'), when prereg_id must be bound ('只能在生成前绑定'), and when to keep collect_ssb enabled ('小区选择、切换、波束管理类课题需要它，别乱关'). This provides clear when-to-use and when-not-to-use guidance.

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