find_trading_range

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

With no annotations, this description fully carries the behavioral transparency burden and does so exceptionally well. It explicitly states the null return condition (fewer than 30 candles), and explains that when no tight range exists it still returns the nearest candidate with qualifies:false, including a warning not to misread that flag as true. This directly prevents a common misinterpretation and discloses edge-case behavior comprehensively.

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 structured with an action-focused opening, a context sentence about Wyckoff usage, and a detailed edge-case explanation. Each section serves a purpose, though the Wyckoff sentence is somewhat long and could be tightened. Overall, it is well-organized and not verbose for the amount of critical behavioral information it conveys.

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?

Even without an output schema, the description outlines the key return fields (upper/lower band, length, flatness), the qualifies flag, and the null behavior. It also connects the tool to a concrete workflow with compute_bar_metrics. It stops short of specifying the exact JSON response shape, but for tool selection and invocation it provides sufficient operational context.

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?

The input schema already provides complete descriptions for all three parameters (symbol, resolution, count), including default, min, and max values. The description adds no significant parameter-level detail beyond referencing the 30-candle minimum, which is already present in the schema. Given the high schema coverage, a baseline score of 3 is appropriate.

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 the specific verb 'Tìm' (find) and a clearly defined resource: the nearest sideways price range (trading range) of a Vietnamese stock, including upper/lower boundaries, length, and flatness. It differentiates itself from sibling tools by explicitly positioning the result as objective structural data for Wyckoff phase identification and referencing compute_bar_metrics as a complementary tool for event-level analysis.

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 clear contextual guidance: it is intended for identifying Wyckoff Accumulation phases and should be combined with compute_bar_metrics for SC/AR/ST/Spring/SOS/LPS detection. It does not enumerate when not to use it or alternative sibling tools, but the primary use case is explicit and actionable.

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