get_time_series

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

Annotations already declare the tool read-only and idempotent. The description adds valuable behavioral context: the result includes 0-100 values plus volume when available, and it instructs the agent to inform the user when plan limits are reached. These details go beyond the structured annotations and help the agent set expectations, so a score of 4 is warranted.

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?

Four sentences, each serving a distinct purpose: core definition, use case, exclusions/alternatives, and error-handling guidance. The most important information is front-loaded and there is no redundancy or fluff. This is a model of concise, action-oriented description writing.

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 tool has an output schema, so return shapes need not be repeated. The description covers the core scope, value range, conditional volume field, usage intent, alternatives, and even an edge-case user communication instruction. For a two-parameter tool with rich schemas and sibling context, this description is fully adequate for an agent to select and invoke the tool correctly.

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 100% and the parameter descriptions in the schema are extremely detailed, especially for 'source' with per-source validation rules and examples. The tool description adds only a small amount of parameter-related meaning (one keyword and one source per request) beyond what the schema already provides. With full schema coverage, the baseline of 3 applies.

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 states a specific verb and resource: 'Full historical series for one keyword and one source' with the value range (0-100). It clearly distinguishes this tool from siblings by naming what it is not for (live trending boards, growth questions) and naming the alternatives. This leaves no ambiguity about the tool's core function.

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 explicit when-to-use guidance ('Use for charting or custom math'), explicit when-not-to-use guidance ('Not for live trending boards'), and names the two sibling tools (get_top_trends, get_growth) as alternatives. It also provides situational handling for rate limiting and quota exhaustion, which is exactly the kind of contextual usage an agent needs.

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