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

Annotations already declare readOnly, idempotent, and openWorld. The description adds critical context that the data is paper-trading only and that this is a convenience wrapper that pre-filters by max_roi. It also includes a disclaimer that the output is informational, not advice. No contradiction with annotations.

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 methodically structured with labeled sections (Purpose, Triggers, When to call, Prerequisites, Next steps, Caveats, Args, Disclaimer). Every section adds distinct value — the trigger examples are targeted at understanding user intent, and the caveat is essential for data context. It is front-loaded with purpose and wrapper definition.

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 read-only, filtered list tool with an output schema, the description covers all necessary context: what it returns, when to invoke it, what parameters mean, what data scope applies, and what to do next. The existence of an output schema means it does not need to enumerate return fields. This is a complete and self-sufficient tool description.

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 0%, but the description compensates fully. It defines market_id with allowed values (crypto, kr_stock, us_stock) and aliases (coin/kr/us), and defines limit as max results with a default of 20. This goes well beyond the bare schema and explains the wrapper's implicit max_roi parameter.

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 clearly it returns 'Losing paper positions (ROI < 0)' and calls itself a wrapper around get_positions(max_roi=-0.01), which precisely describes the action and resource. The sibling get_losing_trades vs positions distinction is clear, and the parenthetical ROI condition disambiguates from other list tools.

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?

Explicitly provides triggers ('what's underwater?', 'show me the red ones'), a 'When to call' line (drawdown / risk review), and a 'Next steps' chain (get_position_detail, get_role_analysis). It also notes there are no prerequisites, and by referencing itself as a convenience wrapper it implies that get_positions is the alternative for unfiltered view.

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