submit_task

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

Annotations are absent, so the description carries the full burden. 'Register' implies a write/create operation, but the description does not disclose whether submission triggers execution, is asynchronous, requires special permissions, or returns a task ID. The input-ref format note is useful but describes parameter syntax, not behavioral side effects.

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?

Two sentences with zero wasted words. The purpose is front-loaded and the single additional sentence conveys actionable input-reference semantics. Every part earns its place.

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?

A submission tool with 8 parameters, no annotations, and only a two-sentence description is under-specified. The presence of an output schema covers return values, but the behavioral ambiguity (queue vs. execute), the relationship to submit_graph, and the command-array format are all unexplained, leaving an agent uncertain about consequences of calling it.

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?

With schema coverage at 0%, the description must compensate, and it partially does: the 'task:<id>/artifact:<name>' and 'artifact:<id>' guidance genuinely adds meaning for the inputs/after parameters that the schema's generic string-object type does not convey. However, the remaining six parameters (name, command, env, outputs, metadata, resources) receive no semantic elaboration.

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 states a specific verb and resource ('Register one task'), making the core action clear. The word 'one' implicitly distinguishes it from the sibling submit_graph, which registers a graph of tasks, though it does not explicitly name that sibling.

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?

No explicit when-to-use or when-not-to-use guidance is provided. The phrase 'one task' weakly implies the alternative submit_graph for multiple related tasks, but the description never names the alternative or gives the decision rule, and no guidance distinguishes it from get_task/list_tasks/cancel_task.

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