weeek_create_task

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

No annotations provided, so the description carries the behavioral burden. It discloses that description field takes HTML (vs Markdown on update), that custom_fields only work with ids here (names only on existing tasks), and that a field not belonging to a project is an error. Decent disclosure but doesn't cover return values, permissions, or auth requirements for a create 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?

Opening sentence is front-loaded and direct. The parenthetical about board_column_id and the date-separation note are efficient. However, the priority explanation and some parameter details are somewhat dense, and the description mixes essential guidance with a few edge-case details that could be trimmed.

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 10-parameter create tool with no output schema and no annotations, this is reasonably complete. It covers the required params, the common gotchas (board_column_id, dates, custom_fields ids), and format quirks. It could mention what the response contains, but for a create operation with 70% schema coverage this is adequate.

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 70%, and the description adds meaningful extras beyond the schema: it explains the HTML/Markdown difference for description, the custom_fields id-vs-name behavior, the board_column_id null semantics (board default), and the priority number-to-label mapping. This goes well beyond what the schema alone provides.

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?

Description states 'Create a task' with a specific verb+resource. It mentions required params (project_id, board_column_id) and a crucial differentiator: dates are set separately via weeek_update_task. However, it doesn't clearly distinguish from related tools like weeek_set_task_parent or weeek_add_task_to_project, though the core create-purpose is apparent.

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 says dates are set separately via weeek_update_task, clearly identifying when NOT to use this tool for date-setting. It also names weeek_list_board_columns as the source for board_column_id. This is strong when-vs-alternative guidance, especially with the sibling set including weeek_update_task and several manage_* tools.

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