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

Annotations only flag destructive/openWorld/idempotent; the description adds substantially more: a ~45 s response window, a 'loading' return state that later resolves via Fit report or read_workspace, page-takeover semantics mirroring add_panel, and a disclosed failure mode where unfound reveals are refused and old content is restored. It also states the Panel keeps its id and placement, which materially reduces the perceived destructiveness.

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 first sentence front-loads the three actions well and nearly every sentence carries real information, but the body collapses into long run-on clauses dense with undefined domain jargon ('Banquish replays your reveals', 'Fit report'), making it hard to parse in one pass. Content is justified; presentation is not.

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 a five-parameter mutation tool with no output schema and no parameter descriptions, this covers timing, intermediate states, failure recovery, id stability, and the composite-Panel case. Only the panel identifier's format and the exact shape of the returned state are left unstated, which is a minor residue rather than a functional gap.

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 0%, so the description must carry everything, and it largely does: candidates, page, exclude (including the empty-array restore case), and mode's item-vs-spot meaning are all defined. The 'panel' parameter is only implicitly identified as an id and its accepted format is never stated, which is the one meaningful gap.

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?

Opens with a specific verb-plus-resource and enumerates the three distinct mutations it performs: re-proposing content, changing exclusions, and switching between Item and Spot mode. It names the siblings it composes with (add_panel, open_page, read_workspace, arrange), so an agent can separate it from read_panel or arrange without inspecting either schema.

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?

Explicitly says when to re-propose (any ambiguous or broken Panel on a Workspace you're working on, plus any the user points you at) and which two paths to take depending on whether the Panel is ambiguous: candidate ids from read_workspace, or a page opened with open_page. The alternatives are named and the selecting condition is stated each time.

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