compare_series

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

No annotations are provided, so the description must carry the burden. It discloses an important behavior: 'Frequency mismatches are reported explicitly and never silently resampled.' But it does not mention whether the operation is read-only, error behavior, or other side effects. The description adds some behavioral context but is not comprehensive.

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 concise sentences cover purpose, use case, a critical behavioral guarantee, and a parameter tip. The most important information is front-loaded, with 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?

Given the tool has 6 parameters and an output schema, the description covers the key decision points: cross-source comparison, frequency mismatch handling, and normalization. It doesn't explain the correlate parameter, but the schema does, and the output schema covers return values. It's complete enough for an agent to select and use the 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 description coverage is 67%, so the description should compensate for gaps. It adds meaningful guidance for 'normalize' ('when units differ') and clarifies that indicators can be from different institutions, but does not explain start_date/end_date or geography beyond the schema. This adds some value but doesn't fully flesh out all parameters.

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 'Compare SEVERAL indicators — possibly from different institutions — side by side,' a specific verb+resource+scope. This clearly distinguishes it from sibling tools like get_series (single series) and compare_regions (regional comparison).

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?

States a clear use case ('This is what makes cross-source questions answerable') with a concrete example, and gives conditional guidance ('Set normalize=true when units differ'). However, it does not explicitly name alternatives or state when not to use this tool, so it falls short of a 5.

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