aiworkhub_task_create_from_template

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

With no annotations, the description carries the full load and does considerable work: it declares this is a manager write, that validation fails closed before create_task (malformed/stale/forged template IDs, unsafe paths, incomplete overrides), that provenance authenticates the expanded contract, and that skill_* fields never leak into allowed_writes/required_outputs. It does not cover auth mechanism, idempotency, or concurrency, so not a 5.

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-loading is good — the role and action are in the first four words — and the length is defensible for a 28-parameter tool. But the prose is dense and repeats the 'forwarded to core.create_task unchanged' formula twice, and the skill_* digression runs long relative to its practical importance.

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 return format need not be explained, though the description usefully notes the receipt and echo_card behavior. For a 28-parameter write tool with zero annotation and zero schema-description coverage, the description is substantive but incomplete: a caller still cannot confidently fill most optional parameters, and sibling routing remains unstated.

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% against 28 parameters, so the description must compensate — and it only does so selectively. It adds real semantics for the trickiest fields (wave_goal_binding's exact shape and non-inference, difficulty's enum values and reasoning-effort meaning, echo_card, the validation/validation_roles pairing, skill_* vocabulary and defaults, template_id provenance), but leaves roughly a dozen parameters (priority, risk_tier, depends_on, forbidden, max_live_tokens, immutable_inputs, mandatory_changed_outputs, allow_empty/unchanged_required_outputs, production_paths beyond a passing mention) with no explanation anywhere.

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 opening line gives a specific verb ('create one task'), a specific resource ('task'), and a discriminating qualifier ('from an authenticated template'), which separates it from aiworkhub_task_create and aiworkhub_task_template_show/list in the sibling set. An agent can route on that sentence alone.

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 description establishes that template-derived fields (allowed_writes, required_outputs, task_type, work_kind) come from expansion, which implies 'use this when a template governs the contract.' But it never states the inverse — when to prefer aiworkhub_task_create directly, or what signals a template is required. Usage is inferable but not explicit.

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