tv_place_order

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

Beyond the destructiveHint annotation, the description adds substantial behavioral context: it explicitly states the tool MUTATES the broker, enforces a paper-trading-only gate, describes order sizing logic (qty from risk_usd/stop distance, market orders using chart price or entry_price), and explains dry_run behavior. This gives the agent a clear mental model of side effects and preconditions. 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 long but dense and well-organized. It front-loads the core purpose and mutation warning, then systematically covers constraints, sizing logic, and dry_run guidance. Every sentence contributes new information; there is no fluff or redundancy. The structure aids quick comprehension for an agent scanning the description.

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 complex tool with 14 parameters and 3 required ones, the description covers all critical behavioral aspects: gate conditions, sizing algorithm, paper-only enforcement, and dry_run safety. The schema handles parameter syntax and enums, so the description need not repeat them. Given the absence of an output schema, the description's note that dry_run returns the exact pre-order is essential and provided. An agent has enough to call it correctly.

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 high (93%), so the baseline is 3. The description adds meaningful semantic value by clarifying non-obvious parameter interactions: how qty is derived from risk_usd and stop distance, how market order sizing depends on chart layout or entry_price, and the purpose of dry_run. It does not repeat schema details but explains relationships between parameters, which is valuable.

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 states a specific verb ('place an order'), the resource ('connected TradingView broker'), and key constraints (mandatory SL, optional TP, paper only). It clearly distinguishes this tool from siblings like tv_close_position or tv_cancel_order by focusing on order entry, leaving no ambiguity about its role.

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 description provides explicit conditions for use: PAPER ONLY, gate limits (risk ≤ 50 USD, max 2 positions, one per symbol, denied symbols), and a recommendation to use dry_run first. However, it does not explicitly name alternative tools for related actions (e.g., modifying brackets via tv_set_position_brackets), so the 'when not to use' aspect is only implied. Given the clarity of the tool's purpose, this is a minor gap.

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