gdex_manage_position

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

Annotations already declare readOnlyHint=true and the description is consistent with a non-mutating preview ('Returns a preview; execute it with gdex_execute_trade'). It adds real behavioral context beyond the annotations: the preview runs 'against its live state', the close/reduce is reduce-only, and it handles the correct side for both longs and shorts. It does not describe slippage handling or failure conditions.

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?

Two tightly packed sentences with the core purpose front-loaded and the execution handoff at the end. Every clause earns its place, though the density means no clause is elaborated enough to fully document the action branches.

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 9-parameter tool with no output schema, the definition covers the high-level flow and confirms a preview is returned, which is the most important thing an agent needs to know. But it leaves half the parameters (dex, accountRef, slippagePct, amount/tokenAddress pairing) unexplained and gives no detail about the preview payload the agent must inspect before executing.

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 56%, so several parameters (dex, accountRef, slippagePct) are undocumented in both places. The description does map the action semantics (close/reduce -> perp, sell -> spot) which helps interpret the enum, but it adds no syntax or format detail beyond that. Baseline 3 is appropriate.

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 ('Preview an exit for an existing position') and splits the two supported cases explicitly: close/reduce a perp vs sell a spot token back to USDC. It names the sibling that performs the follow-up action (gdex_execute_trade), so an agent can distinguish it from execution siblings without reading 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?

Clear context: this is the preview step and execution belongs to gdex_execute_trade, giving the agent a workflow. It does not, however, tell the agent when to choose close vs reduce vs sell, nor how it relates to siblings like gdex_preview_trade or close_perp_position, so the routing is only partially resolved.

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