planka_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 of behavioral disclosure. 'Update' implies mutation, but the description does not state whether the update is partial or full replacement, whether unspecified fields are affected, or whether any permissions or side effects are involved. The opaque 'fields' object adds no behavioral clarity.

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 extremely brief and front-loads the verb and resource, which is structurally efficient. However, it is under-specified to the point of being cryptic—the fragment 'id + fields' reads like a shorthand note rather than a complete, self-contained definition. It earns conciseness points but loses structure points for being too terse.

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?

This is a mutation tool with no annotations, no output schema, and a nested 'fields' object that is completely undocumented. The description does not explain what fields can be updated, what the response looks like, or any usage constraints. An agent without prior Planka knowledge could not invoke this tool correctly.

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 for the lack of parameter documentation. 'id + fields' merely restates the parameter names from the schema without explaining what 'fields' can contain, what field names are supported, or the expected value format. This adds minimal semantic value beyond the raw schema.

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 ('Update') and resource ('a card'), making the core operation clear. It distinguishes from siblings like planka_create_card and planka_delete_card via the 'update' action, though it does not explicitly differentiate from the other update tools beyond naming the resource.

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 alternatives such as planka_create_card, planka_add_card_labels, or planka_remove_card_labels. The description only says 'Update a card,' implying usage context but providing no exclusions, prerequisites, or conditions for choosing it over siblings.

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