Set Form Layout

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds the crucial operational detail those hints cannot: this is a full replacement, so anything not resubmitted is dropped, hence the instruction to send every element to keep. It also discloses the refusal classes and the working-set requirement. It stops short of describing what the call returns or how failures/partial saves behave, which keeps it below a 5.

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?

Four short sentences with the replacement semantics front-loaded and the preconditions following. The phrase "as the Form Layout page saves it, captured and read back" is slightly convoluted, and the refusal sentence would read better placed immediately after the replacement statement, but there is no filler.

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 destructive, open-world mutation with three required params and no output schema, the description covers the replacement contract, the read-first workflow, the update-set precondition and the refusal cases. The main gaps are the unmentioned acknowledge_upgrade_skip parameter and the absence of any note about return behavior or what a partial/failed save does.

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 100%, so the schema already documents all seven parameters including the elements ordering and the update-set working-set constraint. The description reinforces the elements semantics ("the whole new layout, in order, as get_form_layout returns it") and the update-set rule, but adds little the schema does not already say, and never mentions acknowledge_upgrade_skip or the scope/scope_id pairing.

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 and resource — replace one form section's layout with the whole new element list — and implicitly distinguishes itself from the sibling read tool get_form_layout and from set_list_layout by naming the form section target. An agent can identify the operation without opening the 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 routes the agent to get_form_layout first and states the read-before-write rule ("send every element to keep"). It also gives a hard precondition — the update set must be the working set — and names the refusal conditions (sections holding annotations, charts or embedded lists), which is exactly the when-not guidance agents need.

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