reorder_feature

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

With no annotations, the description carries the full burden and discloses key behaviors: moving the associated sketch, rebuilding and remeasuring, refusing the operation if dependency order is violated, and returning both the new order and failing features. It omits permissions, rate limits, or whether dependent features are automatically updated, but the core mutation and failure semantics are well covered.

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 first sentence is front-loaded and efficient, but the following example paragraph is long and somewhat convoluted, using awkward phrasing that requires rereading. It could be trimmed or restructured without losing much 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?

Given no output schema, the description supplies return values (features, failing_features). Given no annotations, it explains rebuild/remeasure and a refusal condition. It is fairly complete for a dependent-feature reorder operation, though it could state prerequisites or effects on other dependents more explicitly.

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 clarifies that 'name' is a feature name from list_features and 'before' is another feature name. This gives meaningful semantics for both parameters, though it does not specify format constraints or whether 'before' must be an existing feature.

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 (Move) and resource (a feature, a list_features name) and the exact effect (to just before another one, rebuild and remeasure). This distinguishes it from sibling tools like add_feature, delete_feature, or suppress_feature, though it does not explicitly name alternatives.

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?

Provides a concrete scenario for use ('For a boss added last that filled holes cut earlier...') and a refusal condition ('Refused... when the feature is built on something at or after that place'). It does not explicitly compare to alternatives like suppress_feature or rebuild, but the when-to-use context is clear.

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