image_keyword_trends

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

No annotations are provided, so the description must fully disclose behavioral aspects. The description covers presentation intent (visualizations, dashboard-like output) and analysis constraints, but it does not disclose key behavioral traits such as whether the tool performs any mutation (assumed read-only, but not stated), any rate limits, data freshness windows, whether it requires specific authentication scopes, or whether results are cached. The missing disclosure of mutation status and other runtime behaviors is a notable gap.

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 well-organized, starting with the core purpose, then behavioral rules, then presentation instructions. It is not excessively long, though the presentation section is somewhat verbose with multiple examples. Each sentence adds value except possibly the last few bullet-like examples (e.g., summary cards, bar charts) which could be condensed without losing meaning. Overall, it earns its length for a tool with no annotations.

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 0 required parameters, no output schema, and no annotations, the description does a reasonable job of covering what the tool does and how to use it. It explains the analysis method (two-window join, deltas) and sets clear expectations about output format and analysis boundaries. However, it lacks any mention of return structure (e.g., what fields are returned, pagination), which would be helpful since there is no output schema. Minor gap.

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?

The schema provides 100% coverage with descriptions for all four parameters (days, order_by, row_limit, min_combined_impressions), so the description is not required to explain them. The baseline of 3 is appropriate because the description adds no additional context beyond what is in the schema. It does not, for example, explain valid ranges for 'days', or clarify that 'order_by' values like 'impressions_delta' are computed deltas.

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 clearly identifies the tool as analyzing 'period-over-period trend for image-search queries' with specific metrics (impressions and position deltas). It explains the mechanics of two equal-length windows joined on query and defines what negative position delta means. This distinguishes it from siblings like image_keyword_overview (likely single-period or snapshot) and image_search_quick_wins (likely opportunity-focused).

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 provides strong guidance on when to use this tool by explaining the period-over-period analysis structure. It also includes explicit usage rules: 'Base your analysis ONLY on the data returned' and 'Do not speculate about causes.' However, it does not explicitly mention when one should use an alternative sibling tool (e.g., image_keyword_overview for static data, or compare_web_vs_image for cross-channel comparison), missing a clear 'when not to use' statement.

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