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

Adds real behavior beyond the annotations: levels become reduce-only exchange triggers so they can only shrink the position, new orders are placed before the old ones are removed (no unprotected gap), and it works while trading is halted. The only gap is what happens on partial failure of the replace sequence, but the ordering note already signals intent to keep the position protected.

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?

Front-loaded with the verb and resource, then usage, exclusions, inputs, execution semantics, and a suggested next call, all in a dense block with no filler sentence. The parenthetical examples carry genuine information rather than padding.

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 3-parameter mutation with hidden exchange-side ordering effects, the definition covers replacement semantics, reduce-only behavior, removal, halt behavior, and the follow-up to verify. An output schema exists, so return-value description is correctly omitted.

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%, so the baseline is 3, but the description adds meaning the schema lacks: a worked allocation example ('50% at 98000, the rest at 101000') and the empty-array removal semantics. It does not add trigger-price directionality (long vs short) because the schema already covers that.

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 (Replace) and resource (a held position's take-profits), including the shape of the payload ('one level or several'), and distinguishes it from the stop-loss and close_position siblings by name. An agent can pick it out of the 35-tool sibling list without opening the schema.

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 timing ('Use after entry'), the mutation cases ('to move or remove them'), and a concrete removal form ('[] removes all'). It also names two exclusions with their correct alternatives: tighten_stop_loss for stops and close_position for immediate exit.

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