create_card

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

With no annotations provided, the description carries full behavioral disclosure burden. It earns credit for the explicit 'This writes to the real board' warning, which conveys real-world side effects beyond the tool's name, plus the ISO-8601 format constraint for `due`. However, it does not disclose permission/auth requirements, reversibility, duplicate-card behavior, or what happens when the named list isn't found, leaving significant gaps for a mutation tool.

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, front-loaded sentences with zero filler. The primary action comes first, followed by the safety-relevant write warning, then the parameter format note. Every sentence 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?

The output schema covers return values, so that omission is acceptable. For a 5-parameter, 3-required mutation tool with real side effects and zero annotations or schema descriptions, the definition covers the essentials (action, write warning, date format) but lacks operational context: how to resolve board/list_name to valid values, whether the action can create duplicate cards, and dependency on sibling read tools. Complete enough for a basic call, but an agent could produce invalid invocations for board or list_name.

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. It does add genuine value for `due` by specifying the ISO-8601 format with a concrete example, which is the most error-prone parameter. It also ties 'named list' to list_name and 'a board' to board. But it fails to clarify whether board and list_name take IDs or human-readable names, and offers no hints for the remaining parameters (name, description), leaving an agent to guess.

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 ('Create a card on a board, in the named list') with an explicit location scope. It clearly distinguishes this from the sibling operations (list_cards, move_card, update_card, add_comment) since creation is the only write-to-add action in the family.

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?

Usage is implied but never stated explicitly. The warning 'This writes to the real board' hints that this tool should not be used for exploratory or dry-run purposes, and the domain (creating vs moving/updating/comments) is inferable from the name and siblings. However, there is no explicit when-to-use guidance, no exclusions, and no pointer to list_boards/list_board_lists as prerequisites for valid board and list_name values.

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