Survivors (Comeback Traders)

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

Annotations already declare readOnlyHint and idempotentHint true and destructiveHint false, so the description correctly avoids restating the safety profile. It adds value by disclosing the metric basis — cumulative realized PnL, explicitly 'Realized-PnL drawdown only' — which prevents mistaking this for an equity- or unrealized-based drawdown scan, and by listing the returned fields, partially compensating for the absent output schema. No contradiction with the 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?

Four short sentences, each earning its place: the definition, the returned fields, the usage phrase, and the metric-scope qualifier. The core definition is front-loaded, with no filler or repetition of schema contents.

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 list query with all-optional, fully documented parameters and annotations covering the safety profile, the description covers the essentials: filter semantics, return fields, and when to use it. Minor gaps remain — the time horizon over which the trough is measured and the meaning of openWorldHint are unstated — but nothing an agent needs to invoke it correctly is missing.

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 description coverage is 100%, so every parameter (limit, offset, maxTrough, minRecovery, and the boolean output-format toggle) already carries its own meaning, defaults, and bounds. The description adds only loose conceptual glue by echoing 'trough depth' and 'recovery amount', which map to maxTrough and minRecovery, so the baseline of 3 applies.

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 leads with a specific verb and resource ('Find comeback traders') and immediately pins down the selection criterion: cumulative realized PnL that hit a deep trough and then recovered to positive. The qualifier 'Realized-PnL drawdown only' plus the plain-language intent ('who blew up but recovered?') make the purpose unambiguous and separable from siblings such as pulse_anti_survivors.

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 gives an explicit, natural-language trigger ('Use for "who blew up but recovered?"'), which is a strong when-to-use signal for an agent. It also narrows scope with 'Realized-PnL drawdown only', but it never names alternatives or states when not to use the tool (e.g., no contrast with pulse_anti_survivors for wallets still underwater).

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