start_generation

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

Annotations only declare the generic write/non-idempotent/non-destructive profile; the description adds real substance on top: it is a background job, poll with the returned id, and constraints are enforced server-side with named runtime failure modes ('generation fails at runtime without them'). It stops short of describing what artifact is produced or whether a partial/failed job leaves state behind.

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, then polling behavior, then constraints — the right order for an agent deciding whether to call. It is dense but every clause carries information; the nested parentheticals around 'lc'/'sa'/'htb' are the only mildly awkward part.

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 13-parameter async mutation tool with no output schema, the description supplies the essential missing pieces: async lifecycle, the id needed for polling, and the attack-specific prerequisites that would otherwise cause silent runtime failures. No output schema exists, so the return value is adequately covered by 'returned dataset id'.

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 only 23% across 13 parameters, so the description must compensate — and it does cover the highest-stakes ones: attack_type prerequisites (lc needs clean_model_id; sa/htb need source_class plus pre-generated .npy files) and base_dataset compatibility. However, eps, vis, seed, device, poison_ratio, target_class, model_architecture, name, and description get no explanation at all, leaving the majority of the surface undocumented in both schema and description.

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?

Opens with a specific verb+resource ('Start generating a poisoned dataset') and immediately scopes it to one of four attack types. It is clearly distinguishable from siblings like get_generation_status, cancel_generation, and run_experiment, and it names the reference tool (list_available_attacks) that enumerates the attack options.

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 states this is asynchronous and tells the agent to poll get_generation_status with the returned dataset id, and to consult list_available_attacks for attack/base_dataset compatibility. What's missing is a clear 'do not call' condition (e.g., don't call while another generation for the same dataset is running) or a direct comparison against run_experiment, which is a plausible alternative for similar work.

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