Create a todo item in the API key's project with a required title and optional note, due date, reminder time, category, and assignee list.
创建待办。需 todo:create 权限（project:manage 等价放行）。 POST /api/projects/{id}/todos 项目由当前 API 密钥自动确定，无需传 projectId。
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true). The description adds context annotations do not carry: the authorization requirement and the fact that the target project is scoped automatically from the API key. That scoping/authorization detail is genuinely valuable for correct invocation.
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?
Three short lines, front-loaded with the action, then permission requirement, then endpoint and scoping rule. Terse and well-ordered with no filler.
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?
No output schema exists, so return values need not be described, and annotations cover the safety profile. The definition supplies auth and project-scoping context but omits any explanation of the required nested body payload, which is the main gap for a create tool with a 7-field nested object.
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 0%, so the description must compensate, yet it only states a negative fact (projectId must NOT be passed). The nested body fields (title, note, dueAt, nodeAt, category, remindAt, assigneeIds) are left entirely unexplained, so an agent gets little help on the fields it actually has to supply.
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?
States a specific verb and resource ('创建待办' / create a todo) and gives the underlying endpoint POST /api/projects/{id}/todos, so the operation is unambiguous. It does not differentiate itself from sibling create tools (e.g. anon_post_todos_template_import), but the core purpose is clear.
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 names the required permission (todo:create, with project:manage as an equivalent) and clarifies that projectId is auto-derived from the API key, which is useful invocation context. However, it gives no explicit when-to-use vs. alternatives or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.