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

Beyond the destructiveHint=true annotation it discloses concrete consequences: clear unlinks the board's brief while photos stay in the library, set wipes the whole item list, add_as_view removes from_garment_id from the board, an automations item pins a workflow that the next brief runs every look through, and a board holds one automation/art direction. It also documents the revision_conflict recovery protocol, which is exactly the operational context annotations cannot carry.

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?

Front-loaded with the trigger sentence and organized action-by-action, with every clause carrying distinct information. It is a dense semicolon-heavy run-on paragraph, so readability suffers slightly, but there is little dead weight.

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 an 8-param destructive mutation with no output schema, it covers side effects, item provenance, ordering dependencies, and the conflict-retry path. It omits what a successful call returns (updated board vs. confirmation), which an agent would want since no output schema exists.

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 coverage is 100% so the baseline is 3, but the description adds reasoning the schema lacks: items are {type, id} sourced from search_uwear_library/read_shoot_board, set removes items by sending the ones to keep, and an automations item must be a workflow_id from brief_inputs.automations. expected_revision's role is also restated with its failure mode.

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+resource ('change what is on the open Shoot Board') and then enumerates all four actions with their distinct effects. An agent can tell it apart from read_shoot_board or add_chat_photos_to_board from the text alone.

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?

Gives per-action usage: add vs set (with the removal-by-keeping trick), clear with/without type, and add_as_view gated on user agreement that two photos show one garment. It routes to search_uwear_library/read_shoot_board for item IDs and read_shoot_board for expected_revision, but never explicitly excludes sibling writers like add_chat_photos_to_board or show_in_shoot_board.

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