nexterm_reposition_snippet

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), lowering the disclosure burden. The description adds no behavioral context beyond the name: it does not explain what 'relative to' means operationally, whether other snippets are shifted, whether organization_id scopes the operation, or what permissions are required.

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 definition is a single, front-loaded sentence with zero waste. It states the core action immediately and does not bury the purpose in unnecessary clauses.

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 mutation tool with no output schema, three parameters, and no schema descriptions, the definition is too sparse. It omits critical context: the direction of reordering, the effect on other snippets, the role of organization_id, and permission requirements. An agent would need to guess at key operational details.

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 0%, so the description must compensate. It loosely maps 'snippet' and 'another snippet' to snippet_id and target_id, but it does not explain the ordering semantics or the purpose of organization_id. Two of three parameters remain effectively undocumented.

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 states a specific verb and resource: 'Reorder a Nexterm snippet'. It also indicates the operation is relative to another snippet, which distinguishes it from update/delete siblings. However, it does not differentiate this from the analogous nexterm_reposition_entry or nexterm_reposition_script tools, nor does it clarify whether the reorder places the snippet before or after the target.

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 no guidance on when to use this tool versus alternatives such as nexterm_update_snippet or the entry/script reposition tools. It does not state prerequisites, side effects, or the conditions under which repositioning is appropriate.

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