prepare_rebalance

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

With no annotations, the description carries full burden. It does disclose the two-step confirmation-token flow, the cap check, and a safety admonition to show the plan first. However, it omits failure behavior (what happens if an order breaches the cap), permission need for market-order execution, and whether rejection to project a bounces back a warning or an error.

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?

Three sentences, front-loaded with the 'STEP 1 of 2' framing that immediately sets process context. Each sentence earns its place: what it is, what it does, how to act on the result. Efficient and well-ordered, though the 'confirmation token' contract could be one clause tighter.

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 tool this complex — two-step confirmation flow, notional cap enforcement, an unexplained JSON weights argument and a threshold parameter — the description is incomplete. It lacks the weights format, threshold semantics, the step-2 (confirm_action) handoff, and the differentiation from compute_rebalance_plan. An agent has just enough to start but not 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 0% and the description gives no parameter-level guidance. It never explains the target_weights_json format (JSON string, which symbol/weight shape), nor what threshold (default 0.01) quantifies — rebalance deviation cutoff, drift tolerance, or something else. An agent cannot construct correct arguments from this text.

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 action — preparing/executing a portfolio rebalance as market orders — and concrete behaviors: recomputes from live data, checks against the notional cap, returns a confirmation token plus the exact plan. Loses a point because the similarly-named sibling compute_rebalance_plan could plausibly do the same thing; nothing here clearly separates this tool from it.

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?

Conveys the two-step flow and instructs 'Show the plan to the user before confirming,' which is useful routing context. But it never names compute_rebalance_plan as the likely alternative, nor says when to prefer this tool over it, nor states exclusions. The agent must guess the difference between prepare_rebalance and compute_rebalance_plan.

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