ib-async-mcp

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

No annotations are provided, yet the description adds zero behavioral context. It does not disclose whether positions are returned for all accounts or require specification, what data structure is returned, whether the operation is idempotent, or any rate limiting concerns. The burden falls entirely on the description, which provides nothing.

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?

While brief, the three-word description represents under-specification rather than efficient conciseness. It wastes the opportunity to provide necessary context (scope, account handling, output format) given the lack of annotations and output schema.

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 trading domain tool with implied complexity (multi-account positions, security types, P&L implications), the description is inadequate. It lacks explanation of return values, account scoping behavior, and relationship to portfolio data—critical gaps for correct agent usage.

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?

With 100% schema description coverage for the single 'account' parameter, the schema sufficiently documents inputs. The description does not add additional semantics (such as explaining behavior when account is omitted), but the high schema coverage means it doesn't need to compensate—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?

The description 'Get all positions.' is tautological—essentially restating the tool name with minor grammatical changes. While it indicates the resource (positions), it lacks specificity about what constitutes a position in this trading context and fails to distinguish from similar sibling tools like get_portfolio or get_open_trades.

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 no guidance on when to use this tool versus alternatives. Given siblings like get_portfolio, get_account_summary, and get_open_trades, the description should clarify the distinction between retrieving positions versus portfolio data or active trades, but offers no such differentiation.

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