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

Annotations flag destructiveHint=true and readOnlyHint=false, and the description usefully qualifies this by stating nothing mutates unless apply is true, plus that the operation is free and re-weights existing run output. It adds real behavioral context beyond the annotation set, though it does not discuss permissions or the exact shape of the comparison output.

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?

Front-loads the core search-plus-validation action and every clause is substantive, but the conversational, dash-heavy style ("The last 30% is the honest number; say so") is denser and less scannable than an ideal 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 4-parameter tool with no output schema, the description covers the mechanics, prerequisites, mutation semantics, objectives, and what the response compares. An agent has everything needed to call it correctly and to explain results to the user.

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 50% (cap and apply are documented in-schema), and the description adds meaningful semantics for the enum by naming all six objectives and noting that min_drawdown/fast_recovery never fall below the current return. However, the phrase "these two" is ambiguous and `id` is left undocumented.

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 (search a portfolio's allocations for the best score), scopes it to the first 70% of the last run, and describes what is returned (out-of-sample 30% vs current and equal-weighted allocations). This clearly distinguishes it from optimize_strategy and run_portfolio among the siblings.

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?

Gives explicit prerequisites ("Needs a run first (run_portfolio)"), cost behavior ("Free: it re-weights the run's results"), and mutation conditions with a directive ("Nothing changes unless `apply` is true — ask the user before applying"). An agent knows exactly when and how to invoke it.

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