get_candles

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the core behavior—returning historical rather than live data in OHLCV bar form—and describes lookback period and bar interval. It does not disclose potential edge behaviors such as timezone handling, corporate action adjustments, or error behavior for invalid symbols.

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 compact and front-loaded: one clear purpose sentence followed by a short Args block with definitions and examples. Every line adds useful information and there is no filler.

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?

With an output schema present, the return structure does not need to be explained in the description. All three parameters are covered with meaningful semantics, and the defaults are visible in the schema. The main missing pieces are explicit sibling routing and behavioral edge cases, but for a simple historical-candles endpoint the description is largely complete.

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 0%, so the docstring must compensate, and it does. It defines symbol as a stock ticker with examples, period as how far back to fetch, and interval as bar size, also with examples. The schema supplies defaults, which the description does not repeat. It stops short of enumerating all valid period/interval values, but gives enough concrete guidance for correct invocation.

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 clearly states a specific verb and resource: 'Get historical OHLCV candlestick bars for a stock symbol.' This distinguishes it from sibling tools like get_quote and get_fundamentals because it is about historical price bars rather than quotes, fundamentals, or indicators. However, it does not explicitly contrast itself with those 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?

Usage is implied: this tool is for historical candle data when the agent needs OHLCV bars. The description provides no explicit guidance on when to prefer this tool over get_quote, get_fundamentals, or get_technical_indicators, nor does it mention exclusions or edge cases.

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