task_import

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

"Bulk create tasks" and the note that rules and playbooks are upserted disclose mutation and side effects, which is useful with no annotations. It does not cover permissions, duplicate handling, atomicity or partial failure, or response behavior for an import operation.

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 front-loaded and dense with useful specifics; the field list and export-object shape earn their space. No filler or repetition is present.

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 complex bulk import with no annotations and no output schema, the description covers the items structure and upsert side effects but leaves actor semantics and import failure or return behavior unclear. It is adequate to attempt a call but not 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 coverage is 0%, and the description compensates strongly for the complex items parameter by defining list vs export-object forms, per-task fields, and optional links. The required actor parameter is never explained, leaving one of the two parameters undocumented.

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 "Bulk create tasks," a specific verb and resource, and distinguishes scope from task_create through bulk import and from rules_import via the export object and upsert behavior. An agent can identify this as the batch-import tool without opening schemas.

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 explains the primary use case: bulk creation and importing an export object containing tasks, rules, and playbooks. It does not explicitly state when to choose task_create/rules_import instead, so alternative routing is implied rather than spelled out.

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