update_element_section

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

Annotations already mark this as a non-read-only mutation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds useful parameter behavior like range-string support, but does not disclose side effects such as overwriting prior section assignments or behavior on invalid IDs. This is adequate given the annotations, but not especially rich.

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 front-loaded with the core purpose, then provides a compact argument list and a minimal example. Bilingual text is not filler for a multilingual API. Every sentence adds useful information without unnecessary elaboration.

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 simple two-parameter mutation tool with no output schema, the description is nearly complete: it defines valid ids formats, explains where to get a valid section ID, and shows usage. Minor gaps include not stating what happens if an ID is invalid or whether the operation replaces existing section assignments, but these are not critical for a low-complexity call.

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 carries the full burden for parameters. It compensates well: ids is explained as int, list, or range string '1to50', and sec_id is described as a new section ID with a pointer to get_section_list for valid values. This goes well beyond the minimal schema which gives no type for ids.

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 action ('Change the section'), the resource ('one or more frame elements'), and includes a Chinese translation. It is easily distinguished from sibling tools like update_element_material, update_element_nodes, and update_section_property because the scope is explicitly the section assignment of frame elements.

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 concrete usage guidance: ids accepts int, list, or range string '1to50', and sec_id should be looked up via get_section_list. The example clarifies a common batch call. It does not explicitly name alternative tools or exclusion conditions, but the usage context is clear enough for an agent to proceed.

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