Create Basecamp Todo

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

Annotations already declare this as a non-read-only, non-idempotent write, but the description adds real behavioral detail beyond them: mentions trigger notifications to the mentioned person, an invalid person ID causes an error and writes nothing (atomic failure), and bc-attachment tags are auto-enriched after saving. It does not, however, describe the response payload or permission requirements.

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 one-line purpose is properly front-loaded, and the allowed-tag list is genuinely useful reference material for a tool with no output schema or docs field. However, the block is large and uneven: the paragraph-spacing explanation and the bc-attachment collapse rules (which describe behavior of append/prepend/search_replace operations, not this tool) consume significant budget and repeat points already implied.

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 the hardest part of the call — composing valid Basecamp HTML content — the description is thorough. But for a 7-parameter creation tool with no output schema, it omits where todolist_id should be sourced (basecamp_get_todoset / basecamp_list_todos) and never says what the call returns, so an agent cannot close the loop after creating the todo.

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 71% schema coverage, the schema already documents due_on, notify, starts_on, todolist_id, and assignee_ids; the description's heavy HTML contract adds substantial meaning for the undocumented 'content' parameter, including mention and attachment syntax and validation behavior. The 'title' parameter remains undocumented in both places, which keeps this short of a 5.

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 sentence gives a specific verb and resource ('Create a new todo item in a todo list'), which is enough to distinguish it from basecamp_create_todolist or basecamp_create_message by resource type. It never explicitly contrasts itself with those siblings, though, so the differentiation is inferable rather than stated.

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?

There is no guidance on when to use this tool versus siblings like basecamp_create_todolist, basecamp_create_comment, or basecamp_create_kanban_card, and no stated prerequisite (e.g., where todolist_id must come from). The description does route to basecamp_list_people and basecamp_create_attachment for obtaining IDs and SGIDs, which is procedural help, but it is about building the content payload rather than tool selection.

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