reorder_user_field_schema

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

No annotations are provided, so the description bears the full burden of behavioral disclosure. The description reveals no side effects, authentication requirements, rate limits, or failure modes (e.g., what happens if a field key doesn't exist). It is a straightforward reorder operation without additional behavioral context, warranting a moderate score.

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 a single paragraph with front-loaded purpose ('Reorder displayed user table columns... Use this when...'). The examples are concise and illustrative, adding practical guidance without redundancy. Every sentence serves a clear purpose.

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?

Given the moderate complexity (4 params, no output schema), the description covers the main use case well: reordering via relative or absolute positions. It lacks explanation of what happens on success or error, and does not address parameter exclusivity. However, it is close to complete for a focused reorder tool.

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 baseline is 3. The description adds value by giving natural language examples mapping to parameter combinations (e.g., 'move department after email' → after parameter), but it does not explain the semantics of required vs. not-allowed parameter combinations (e.g., that after, before, and position are mutually exclusive). The examples illustrate usage but leave restrictions implicit.

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 exactly what the tool does: 'Reorder displayed user table columns in the user field schema.' The verb 'reorder' is specific to the resource 'displayed user table columns'. Among siblings like get_user_field_schema, refresh_user_field_schema, and update_user_field_schema, this description uniquely distinguishes the reordering action.

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 explicitly says 'Use this when the operator asks to move a column left, right, first, last, before another field, or after another field.' It also instructs the agent that field and target values must be exact field keys from get_user_field_schema, listing examples. This tells the agent when to invoke this tool and what inputs to use, effectively differentiating it from siblings like update_user_field_schema.

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