conduyt_reorder_smart_views

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

No annotations exist, so the description carries the full load and does real work: it discloses the admin-key requirement, the 200-item cap, the no-duplicates rule, and the non-obvious side effect that omitted views retain a stale position. It does not say how invalid/unknown UUIDs or partial failures are handled, which is the remaining gap for an unannotated mutation tool.

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?

Three tight sentences: action and auth first, the critical full-list rule second, the sibling redirect last. Nothing is repeated from the schema and every clause carries new information.

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 one-parameter tool with no annotations and no output schema, this is nearly sufficient: the destructive-adjacent semantic (omissions leave stale positions) and the alternative tool are both covered. The missing piece is disambiguation from conduyt_move_smart_view and any statement of what a successful response or an invalid id produces.

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 already 100%, but the description adds meaning the schema cannot: the array must be the complete set of views (not a partial delta), the source is conduyt_list_smart_views, and position in the array equals priority. That turns a bare array into a well-understood contract.

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: set the SIDEBAR order of Smart Views, with the admin-key qualifier. It clearly separates itself from conduyt_set_smart_dialing_order. However, the close sibling conduyt_move_smart_view (single-view move) is never mentioned, so an agent must still infer which of the two reordering tools to pick.

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 explicit prerequisites and procedure: fetch ids from conduyt_list_smart_views, send every id in the wanted order. It also names the alternative (conduyt_set_smart_dialing_order) and the condition that selects it (dialing priority, dial-enabled ids only).

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