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

With no annotations, the description carries the behavioral burden. It discloses useful traits: both legs are closed, orders are market, and the operation is reduce-only. However, it does not mention side effects, failure modes, irreversibility, or permission requirements, which are relevant for a position-closing mutation tool.

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 short and front-loaded, with the primary action and key execution mode in a single sentence. The 'Params: positionId, reason (optional)' tail is slightly redundant with the schema, but it is not bloated.

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?

The description covers the core behavior but omits important context for a financially risky operation: whether the position must already exist, what happens if one leg fails, whether the operation is reversible, and what the return value contains. It is adequate for a simple close action but not fully complete.

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 should compensate by explaining what 'positionId' refers to and what 'reason' is used for. It only lists the parameter names and marks 'reason' as optional, which adds little beyond what the schema already shows.

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 uses a specific verb ('Close'), a clear resource ('hedged position'), and adds execution details (both legs, market, reduce-only) that differentiate it from the sibling 'close_position'. An agent can confidently identify what this tool does without inspecting 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?

The term 'hedged position' implies when to use this tool, but the description does not explicitly say when to prefer it over 'close_position' or 'adjust_hedge'. It provides implied usage context but no direct exclusions or alternative guidance.

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