get_clarity_historical_insights

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

With no annotations provided, the description fully discloses behavioral traits: it reads only local files, never calls the API, explicitly lists found/missing dates so gaps are visible, and states there is no backfill possibility. It also mentions the performance consideration of uncompressed days for wide ranges, which is beyond what any structured field could convey.

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 front-loaded with the primary purpose and each subsequent sentence adds critical constraint or usage detail. Despite being six sentences long, there is no filler; every sentence reveals a non-obvious aspect of the tool's behavior or a practical tip.

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's complexity—historical local data, API limitations, and gap reporting—the description covers all necessary context: it clarifies the source (local snapshots), the constraint (no API access), the gap behavior, the optional filter, and performance advice. Even without an output schema, it explains what the result will include (found/missing dates), making the tool fully understandable.

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%, so the baseline is 3. The description reinforces inclusive date handling and UTC, but its added value comes from clarifying that urlFilter 'post-filters each found day's rows' and advising its use for wide date ranges to avoid oversized responses. This goes beyond the schema's brief descriptions, though much of the core meaning is already in the structured definitions.

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 a specific verb and resource: 'Return locally-captured Clarity snapshots for each day from startDate to endDate.' It clearly distinguishes itself from siblings by emphasizing it reads local files only and never calls the Clarity API, contrasting with get_clarity_insights and capture_clarity_snapshot.

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 explicitly explains when to use this tool versus alternatives: it can only retrieve previously captured days, cannot use the Clarity API due to its 1-3 day limitation, and cannot backfill missing dates. It also references get_clarity_insights for urlFilter semantics and recommends passing urlFilter for wide date ranges to reduce data volume.

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