get_search_by_page_query

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

With no annotations provided, the description carries some burden, but it discloses a key behavioral trait: the data lags by 2 days (implied via the 'days' parameter description, not directly in the main description). The main description itself is minimal, but the schema's parameter descriptions provide important context about default behavior (28 days) and data lag. Since the tool is a read-only query operation, the main description doesn't disclose mutation or side effects, but that's expected. It could mention that results are limited by rowLimit (though that's in schema). Given no annotations, the description does not add much beyond basic scope.

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 a single, efficient sentence that covers purpose and key outputs without fluff. It is front-loaded with the core action. No unnecessary words. It earns a high score for conciseness, though it could slightly improve by adding a hint about when to use it, but that would lengthen it.

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 moderate complexity (6 params, 2 required) and high schema coverage, the description is adequate but not complete. It covers the purpose but lacks explicit guidance on parameters like date handling (though schema covers it) and doesn't explain what the output structure looks like (though no output schema exists). Since the schema is rich, the description doesn't need to re-explain everything, but a sentence about typical use cases would improve completeness. Overall, it's sufficient for an agent to call correctly if it reads the schema.

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%, so the schema already fully documents all six parameters, including the crucial 'siteUrl' format (URL-prefix vs sc-domain) and the date behavior. The description adds no additional parameter meaning beyond what the schema provides. For a tool with high schema coverage, baseline 3 is appropriate. The description doesn't need to repeat schema details.

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 states a specific verb ('Get'), resource ('search queries'), and scope ('traffic to one specific page'), and lists the metrics returned (clicks, impressions, CTR, position). It distinguishes from sibling tools like get_search_analytics by focusing on a single page's queries, though it doesn't explicitly name a sibling. It is clear and specific enough for an agent to understand its 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 implies usage for page-level query analysis, but provides no explicit guidance on when to use this tool versus alternatives like get_search_analytics or get_advanced_search_analytics. It doesn't state any exclusions or conditions. The context makes it obvious it's for one page, but an agent might not know if this is the best tool for, say, detailed query analysis across a site.

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