extend_history

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

Annotations declare readOnlyHint=false with destructiveHint=false, so the agent knows this mutates state but is non-destructive; the description explains what the mutation is by describing the backward walk from the oldest cached year/month and the stop-at-first-empty-chunk rule. It also introduces the broker-limit concept, which is real behavioral context beyond the annotations. What it omits is where the downloaded data lands (cache vs disk) and what the response contains besides reached_broker_limit.

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 the core action and stopping rule, then organized as one line per kind, which is an effective structure for a mode-switching parameter. A few statements are clipped to the point of ambiguity ('A bar outside that month does not count') and could be tightened without losing the semantics.

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?

There is no output schema, yet the description references a return field (reached_broker_limit) without documenting the rest of the response shape, so an agent cannot predict what comes back from a chunk. Given a stateful, looping download tool with one required and two optional parameters, more detail on returns and on the effect on cached data would be warranted.

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 description carries the full burden, and it largely does: each kind value (d1, m1, ticks) is given distinct semantics including its walk unit and origin point. The weak spot is max_steps, described only as 'the number of months in one call', which reads inconsistently with kind=d1 that walks whole years, and symbol is left entirely to the schema.

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?

States a specific verb and resource ('Download older history one chunk at a time') plus the terminating rule ('stop at the first empty chunk'), and then disambiguates the three modes of the tool. An agent can tell this apart from probe_history or history_coverage because those inspect rather than extend cached data.

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 clear operational guidance for iteration ('Call again when reached_broker_limit is false'), which is genuinely useful for driving repeated chunks. However it never states when to prefer this over the sibling tools probe_history, history_coverage, or copy_ticks, and it doesn't state prerequisites such as needing a select_symbol first.

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