describe_series

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

With no annotations, the description must carry behavioral info. It discloses that as_of is required and the call fails without it, and implies a read-only profile operation. It does not describe error handling for invalid symbols, rate limits, or any side effects, leaving some behavioral gaps.

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?

Three sentences plus two examples with no wasted words. The purpose is front-loaded, and the examples are practical and directly illustrate correct invocation.

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?

The description covers what the tool returns, when to use it, and the required parameter. Given an output schema exists, it need not detail return structure. It could mention read-only nature, but that is minor. Overall it is complete for a simple profiling tool.

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 100% and the as_of schema description is already very detailed. The tool description adds only the reinforcement that as_of is required and provides usage examples, which is marginal beyond schema. Baseline 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 uses the verb 'Profile' with a specific resource ('one series as of a date') and enumerates the exact outputs (coverage, gaps, frequency, last close, annualised volatility, max drawdown). It also positions the tool as a pre-backtest check, distinguishing it from siblings like run_backtest and get_bars.

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 explicitly states the use case: 'Use it to check a symbol has enough history before running a backtest on it.' It also notes the required as_of parameter and failure mode. However, it does not mention when not to use it or name alternatives, so it lacks the full when/when-not guidance.

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