custom_analysis

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

Beyond the readOnlyHint/openWorldHint annotations, it discloses what the conditions block actually computes (active now, event count and dates, forward 5/20-session returns with a t-statistic vs all bars) and what comes back (JSON last values + condition reports, plus PNG when chart is true). That is real behavioral context an agent cannot get from the schema. It stops short of describing failure modes or data-window limits.

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-loaded with a one-line purpose, then labeled blocks (indicators:, series:, conditions:, levels:) that let an agent jump to the relevant parameter. The multi-line JSON examples are long but each demonstrates a distinct concept; minor trimming would still earn its keep.

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 an 8-parameter tool with nested specs and no output schema, the description supplies both the composition grammar and the return shape, which covers the hardest gaps. Missing only secondary details like the default period window and the chart/title interaction.

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 0% schema description coverage, the description carries the burden and mostly succeeds: it supplies worked examples with concrete shapes for indicators, series, conditions, and levels, and notes that chart controls PNG emission. It leaves period's accepted formats and title's effect unexplained, and the condition mode ('edge' vs 'state') distinction is only in the nested schema, not the description.

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 opens with a specific verb + resource + scope: 'User-defined technical analysis on one ticker, with an optional chart.' The word 'user-defined' distinguishes it from the preset-oriented sibling technical_indicators, and it names list_indicator_catalog as the discovery path. An agent can tell this is the escape hatch for arbitrary indicator/condition composition.

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?

It gives a concrete sequencing rule: 'Call list_indicator_catalog first to see indicators, parameters and functions,' which prevents blind guessing at fn names. It does not state when to prefer this over technical_indicators or risk_metrics, so the alternative-selection guidance is implicit rather than explicit.

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