Update Card

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

With no annotations provided, the description carries the full burden for behavioral disclosure. It adds the important partial-update semantics (empty fields are no-ops) and the ISO 8601 date format requirement, which are real behavioral traits beyond the tool name. However, it does not mention whether updates are destructive, require permissions, or affect other card fields, leaving notable 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?

The description is a single, dense sentence that front-loads the verb, resource, and fields, then adds the format and behavior. It contains no fluff and every clause adds value. Slightly more structure could include the identifying parameters, but as written it is efficient and readable.

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, but the description leaves major gaps for a mutation tool. It does not explain how the card is identified via board_name and card_name, which are required parameters, nor does it note prerequisites like an existing card/board or error conditions. The description addresses the update fields but not the targeting mechanism, making it incomplete for safe invocation.

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 maps 'name, description, due date' to new_name, new_description, and due_date, and adds the empty-field meaning. However, it does not explain the required identifiers board_name and card_name, which are essential for the agent to target the correct card. The description covers only 3 of 5 parameters meaningfully.

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 clearly states the tool updates a card's name, description, or due date, with a specific verb and resource. It differentiates from siblings like create_card, archive_card, and move_card by explicitly listing the updatable fields, so an agent can identify the correct operation.

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 gives clear context for when to use it: when changing one or more of the three named fields. It also provides a usage rule, 'Leave fields empty to keep them unchanged,' which guides the agent on how to perform a partial update. It does not explicitly name alternatives or exclusions, but the context is sufficiently clear.

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