GSCPAP - Google Search Console, GA4, PageSpeed Insights & live SERPs MCP

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds that the result is coverage/date-range information, which is genuine behavioral context. It says nothing about auth requirements, latency, or whether coverage is per-property granularity beyond the term 'per-site', so it stays at an adequate-plus level.

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?

Two sentences, roughly fifteen words, with purpose first and the call-ordering instruction second. Nothing is redundant and nothing important is buried.

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?

This is a simple, annotation-covered, read-only tool with an output schema, so return values need not be spelled out. Purpose plus call ordering is what an agent needs here. It loses a point only because 'per-site' versus the parameter's all-properties default is not reconciled in prose.

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 single site_url parameter already documents the 'if provided / if None' branch, so the schema does the work. The description's 'per-site' wording only loosely signals that site_url scopes the result; it adds no format or semantics beyond the schema. Baseline 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 the resource and scope concretely ('Per-site archive coverage') and immediately ties it to a sibling tool, so an agent knows this reports available archive date ranges rather than querying them. It stops just short of a full verb+object phrasing like 'Get archive coverage per site', but the meaning is unambiguous.

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?

It gives explicit sequencing guidance — 'Use this before search_analytics_archive' — which names both the alternative and the condition that selects it. There is no statement of when *not* to use it, but for a one-parameter preflight tool the positive guidance is essentially complete.

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

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

Annotations already declare readOnly/openWorld/non-destructive, so the description's job is to add operational context — and it does: inspections run concurrently, wall time approaches the slowest single URL, and each URL yields either a result or an error (partial failure is tolerated). What's missing is whether quota is consumed per URL or per call, which matters a lot for a 10x fan-out.

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?

Front-loaded with the capability and the cap in the first sentence, then a short rationale for the concurrency design. The 50s anecdote is slightly chatty but earns its place by explaining why batching is worth using; nothing is redundant.

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?

An output schema exists, so return-value explanation is legitimately omitted and the per-URL error note is a nice touch. But with 0% schema coverage on three parameters and no mention of sibling inspect_url, an agent still has to guess at argument semantics and at when to prefer this over the single-URL 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 0% across three parameters, so the description must compensate and largely does not. It only constrains inspection_urls (max 10); site_url's required format/meaning and language_code's role in the inspection result are left entirely undocumented.

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?

States a specific verb and resource ('Inspect up to 10 URLs at once') plus the batch ceiling and the per-URL success/error return shape. It is clearly distinguishable from the singular inspect_url sibling by the batch framing, though it never names that sibling explicitly.

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 10-URL cap and the concurrency note imply this is the bulk alternative to inspect_url, but the description never says 'use inspect_url for a single URL' or when batching is inappropriate. No prerequisites are given (e.g. that site_url must be a verified property) and no quota/rate-limit guidance for a call that fans out to many Google inspections.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered and the description adds nothing on top of it. It says nothing about the comparison semantics, what metrics are returned (clicks, impressions, CTR, position?), or whether deltas are computed server-side.

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?

A single front-loaded sentence with zero padding, but at nine words it is under-specification rather than conciseness. The brevity costs information an agent needs rather than saving 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?

With eight parameters, 13% schema coverage, no output schema and no annotations covering semantics, the description carries most of the explanatory burden and discharges almost none of it. An agent would have to infer date formats, the meaning of the current/previous pairing, and the shape of the comparison result.

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 13% – only the dimensions parameter is documented, and that documentation lives in the schema rather than the description. Five required parameters (site_url and the four date bounds) have no stated format, no explanation of the current vs previous pairing, and no note on defaults for row_limit or search_type; the description supplies none of this.

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 pairs a specific verb ("compare") with a resource ("performance") and the notion of two date ranges, which is more than a restatement of the name. However, it never states this is Search Console data, nor does it distinguish the tool from close siblings like get_performance_overview or ga4_compare_periods – only the separate title carries that disambiguation.

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?

There is no when-to-use guidance and no mention of alternatives. An agent receives no signal about when to pick this over get_performance_overview (single range) or ga4_compare_periods (GA4 data), or whether the two ranges must be equal length, adjacent, or non-overlapping.

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

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

Annotations only declare readOnly/openWorld/non-destructive; the description goes far beyond by disclosing the exact GA4 filter (landingPage + sessionSource google AND sessionMedium organic), why the channel group is not used, that ga4_conversions can exceed ga4_sessions, and that gsc_clicks will not equal ga4_sessions for stated reasons. These are interpretation-critical behaviors no annotation could carry.

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?

It is long, but for a two-source join most paragraphs earn their place, and the summary sentence is front-loaded before the scoping and caveat sections. Minor deductions for a garbled trailing clause ("one GA4 has no data for gets 0") and some restatement of the GA4-vs-GSC mismatch point across paragraphs.

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?

For a complex cross-source join with four parameters, it covers the scope definition, join key and normalization rules, URL merging behavior, host separation, time zone mismatch and null handling. An output schema exists, yet the description still clarifies key row fields like ga4_scope and gsc_urls, leaving nothing an agent needs unresolved.

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, but the description adds real meaning: `limit` applies to top pages ranked by Search Console clicks, and both sides use the same date window (including the Search Console lag). It does not discuss site_url/property_id alignment beyond what the schema says.

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 opening line states a specific verb and resource pair — Google Search clicks per page joined to GA4 sessions, key events and revenue — and immediately frames it as a per-page join. This is distinguishable from siblings like ga4_top_pages or get_search_by_page_query because it explicitly combines both data sources rather than reporting one.

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?

It gives concrete example questions the tool answers ("which pages bring search clicks AND convert?", "which top-ranking pages get zero conversions?") and explains it takes top pages by Search Console clicks. It never explicitly names an alternative sibling or a when-not-to-use condition, so it stops 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.

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered structurally. The description adds the useful behavioral detail of what counts as a duplicate (URL-prefix plus domain property for the same domain), but says nothing about scope, e.g. whether it scans all sites in the account or a subset.

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?

A single front-loaded sentence with no filler; the defining criterion is stated immediately. Nothing could be removed without losing meaning.

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?

With an output schema present, return values need no explanation, and there are no parameters to document. The remaining gap is scope — whether the scan covers all accessible sites or only some — but for a zero-arg read-only detector the definition is otherwise sufficient.

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 tool takes zero parameters, so there are no parameter semantics to explain and the baseline of 4 applies. Nothing in the description misleads about inputs, and the absence of arguments is consistent with the empty schema.

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 uses a specific verb ('Find') and a precise resource ('domains registered as both URL-prefix AND domain properties'), and the definition of 'duplicate' is spelled out rather than left to inference. It is clear what the tool returns conceptually, though it does not explicitly contrast itself with the nearby list_sites or get_site_details siblings.

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?

Usage is only implied: an agent can infer this is the tool to run when auditing Search Console property configuration, but there is no explicit 'use this when' statement, no prerequisites, and no named alternative such as list_sites for enumerating properties.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint, so safety is covered; the description goes further by disclosing the output ordering (est_clicks_lost) and the epistemic limitation that GSC and SERP tools cannot actually observe AI Overviews. It also enumerates competing explanations (Featured Snippet, Map Pack, ads, weak title/snippet, brand queries), which is behaviorally useful. It stops short of describing pagination or truncation behavior at row_limit.

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 core definition is front-loaded in the first sentence, followed by qualification logic, then caveats and a next step. Density is high but every clause carries operational meaning — no filler or restatement of the title.

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?

With an output schema present, the description does not need to explain return shapes, and it uses that space instead for the heuristic, its failure modes, and the verification path. For a 9-parameter diagnostic tool that is explicitly a heuristic, nothing an agent needs to call or interpret it correctly is missing.

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 only 56%, and several thresholds (max_position, max_position_change, min_impressions, min_ctr_drop) have no schema descriptions at all, so this text carries real weight. It supplies the actual qualification rule across both windows, including the non-obvious detail that baseline requires only half of min_impressions, and explains that min_ctr_drop is a fraction (0.30 = 30%) and that exclude_terms are case-insensitive substrings for brand words.

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, testable definition: queries whose CTR fell while position held, framed as the footprint of an AI Overview or answer box. That verb+resource+signal combination is distinct from siblings like find_content_decay or find_quick_wins, so an agent can route without opening a schema.

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?

It clearly states when results apply (CTR drop with stable position) and prescribes a verification workflow: check a few rows with serp_top_results before acting, and label output as a suspicion rather than a measurement. It does not explicitly say when to choose find_content_decay or find_quick_wins instead, which is the main gap for a diagnostic tool with many analytics siblings.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds essentially nothing beyond that: it does not mention how queries are ranked, what thresholds are applied by default, how large the result set may be, or what the output contains. Only the conceptual definition of cannibalization adds value.

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?

A single tightly worded sentence that front-loads the core action, with the technical term aiding recognition. It is not padded, though its brevity is partly under-specification rather than efficiency.

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?

An output schema exists so return values need no explanation, but a six-parameter analysis tool with zero schema description coverage and zero usage guidance is significantly under-documented. An agent cannot know how to set thresholds or date ranges from this definition alone.

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 0% across six parameters, so the description carries the full burden and fails to do so. The phrase 'multiple pages compete' loosely hints at min_pages_per_query, but min_impressions, start_date, end_date, row_limit, and site_url are never explained, nor are their defaults or units.

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 gives a specific verb+resource ('Find queries where multiple pages compete') and defines the term 'keyword cannibalization' in parentheses, so the agent knows exactly what class of analysis this performs. It is implicitly distinguishable from siblings like find_quick_wins or find_content_decay, but it never names or contrasts them explicitly.

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?

There is no when-to-use guidance, no prerequisites (e.g. site must be connected to Search Console), and no mention of alternatives such as find_quick_wins or get_search_by_page_query. Usage must be inferred entirely from the tool name and description.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds the comparison semantics (click drop versus prior period), which is genuine context beyond the annotations, but it does not mention that results are gated by min_impressions_previous, what window 'prior period' uses, or truncation via row_limit.

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?

A single front-loaded sentence with no filler, which is good, but it is under-specified rather than economical for a 6-parameter analytical tool. Nothing is wasted, yet too little is said.

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?

An output schema exists, so return values need not be explained, but the tool's complexity (comparison windows, dimension choice, impression floor, row cap) is not addressed at all. An agent could not confidently set four of the six parameters from this definition.

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 0% across 6 parameters, so the description must carry the load and does not. Only decline_threshold_pct is referenced, and even that only by name; days, dimension, min_impressions_previous, row_limit, and site_url are left entirely to the bare schema types and defaults.

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?

States a specific verb and resource: finding pages or queries whose clicks dropped by at least decline_threshold_pct versus the prior period. That makes it distinguishable from siblings like find_dead_pages, find_new_pages, and find_quick_wins, though it never names those alternatives explicitly.

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 no guidance on when to choose this over find_dead_pages, find_new_pages, or compare_periods, nor any prerequisites for the comparison window. The agent must infer selection criteria from the sibling list alone.

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

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

Annotations already cover safety (readOnly, non-destructive) and open-world scope, so the description's job is interpretive context, which it delivers: the two result groups mean opposite remediation work, and the impression-vs-click distinction tells the agent how to act on results. It adds no operational details like rate limits or result ordering, though ordering is documented in the schema.

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 opening sentence front-loads purpose and scope, and the contrast with find_content_decay follows immediately. Three paragraphs is slightly longer than necessary and the '77% of new pages' statistic is illustrative rather than actionable, but no sentence is pure 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?

An output schema exists, so return formatting needn't be described; what matters is how to interpret the two buckets, which the description explains with the diagnostic consequences of each. Combined with full schema coverage, an agent has everything needed to select the tool and act on its output.

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 site_url, row_limit and min_age_days are already fully documented, including the impression-based ordering and the pointer to find_new_pages for young pages. The description adds nothing about parameters beyond an implicit reference to 'months' of history, so baseline 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?

States a specific verb and resource ('Pages Search Console has shown for months that have never earned a click') plus the defining output split between listing and ranking problems. It also explicitly contrasts with find_content_decay, so an agent can separate the two without opening either schema.

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?

Clearly frames the when-to-use case against find_content_decay ('had traffic and lost it' vs 'never had any') and explains the diagnostic split that justifies the call. It does not route against other near-neighbors such as find_quick_wins, which also deals with high-impression/low-click pages, so guidance is clear but not exhaustive.

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

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

Annotations already declare read-only, non-destructive, open-world behavior, so the bar is lower; the description still adds real value by explaining that 'new' means first impression rather than publication and that never-shown pages are invisible to the tool. These are genuine behavioral caveats beyond the annotations, though nothing is said about data freshness limits beyond the archived-date note carried in the schema.

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?

Purpose is front-loaded in the first sentence, which is good, but the long block of statistics (77%, 90%, 22x, 37,295 pages) is persuasive padding that restates the same point three times. The definitional paragraph at the end is more valuable than the benchmark recital and could have come earlier.

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?

An output schema exists, so return-shape explanation is not needed, and the description covers what the tool does, the meaning of its core concept, and its main limitation. What remains thin is guidance on choosing this over adjacent analysis tools, which matters given a sibling list this large.

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 parameters are already documented, including that row_limit orders by impressions. The description's statistical argument adds rationale for the seven-day default but no syntax, units, or edge-case behavior beyond the schema, so this sits at the baseline for a fully documented schema.

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?

Opens with a specific verb+resource pair: pages Search Console started showing in the last N days, plus whether they earned a click. The follow-up paragraph precisely narrows the definition of 'new' to first-impression date, which separates it cleanly from siblings like find_dead_pages or find_content_decay.

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?

Gives strong guidance on the default window (why seven days) and explicitly states the tool's blind spot: pages Google has never shown cannot appear. It does not name alternatives such as find_quick_wins or compare_periods, so routing between similar analysis tools is left implicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered and the description need not restate it. What the description adds is a conceptual definition of the filter logic (high impressions + low CTR + page 1-2), which helps the agent trust the result set. It does not disclose the default date window, default row limit, or how thresholds default, which are meaningful behavioral traits for a data-query tool.

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?

A single front-loaded sentence with zero filler; the scoping criteria come first and the actionable interpretation is parenthesized at the end. Nothing can be removed without losing meaning.

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?

For an 8-parameter analytics tool with no schema descriptions, the description is under-specified. Most importantly, it never indicates the time window analysed when start_date/end_date are left null, so the agent cannot reason about what period the 'quick wins' reflect, nor what row_limit does to results. The existence of an output schema relieves it of explaining return values, but the input-side gaps remain substantial.

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 0% across 8 parameters, so the description carries the full burden and only partially meets it. It conceptually maps to max_ctr ('low CTR'), min_impressions ('high impressions'), and the position bounds ('page 1-2'), but leaves site_url, start_date, end_date, and row_limit completely undefined, and gives no units (CTR as a 0-1 fraction) or defaults. The page-vs-position mapping is also loose relative to the actual min_position=5/max_position=20 defaults.

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 names a specific verb (find) and a precisely bounded resource: queries sitting in positions corresponding to pages 1-2 with high impressions but low CTR. The parenthetical '(snippet/title fix candidates)' states the actionable outcome, which separates it from diagnostic siblings like find_content_decay or find_cannibalization. It stops short of naming an explicit sibling alternative, so it is a 4 rather than a 5.

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?

Usage is implied rather than stated: the phrase 'snippet/title fix candidates' tells the agent this is for identifying metadata-rewrite opportunities, but there is no explicit when-to-use/when-not framing. No alternative sibling (e.g. find_content_decay, find_cannibalization, get_search_by_page_query) is mentioned for adjacent intents. The agent can infer intent but must guess at boundaries.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, yet the description adds substantive behavior: the AI-session attribution rule (channel OR known source), the ~10% gap filed as Referral, the cap of 25 properties for "all", the partial final ISO week, and the caveat that engines[].key_events are sums that exceed sessions. It also warns against over-claiming AI conversion superiority from an aggregate median, which is real interpretive guidance.

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?

It is front-loaded with purpose, then usage, then result interpretation, with zero filler sentences — each claim (attribution rule, ratio choice, key-event caveat, partial week) is actionable. The length is justified by analytical complexity, though the block is dense enough that light trimming of the parenthetical measurement asides would help scanning.

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?

An output schema exists, yet the description goes further and explains how to read the key fields (ai_to_organic vs ai_share_of_total, pages paired with organic sessions, rates from ai_totals). For a read-only analytics tool with 3 simple params, nothing an agent needs to invoke or interpret it is missing.

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 already 100%, so the baseline is 3; the description still adds meaning beyond the schema for property_id by explaining that "all" returns one summary row per property limited to the first 25 the user can see. The days and page_limit semantics are already fully covered in the schema, so no additional credit is warranted there.

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 opening sentence names a specific resource (traffic from AI assistants), the named engines, the breakdowns (engines, pages), and the comparison against Google organic. This is clearly separable from generic siblings like ga4_traffic_sources or ga4_top_pages because it is scoped to AI-assistant-referred sessions.

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?

It lists concrete user questions the tool answers ("do AI assistants recommend my site?", "how much traffic does ChatGPT send?", GEO/AEO/LLM visibility) and states an explicit boundary: it measures visits only and cannot see mentions without a click. It also flags the portfolio-comparison mode via property_id="all", so the agent knows both when to reach for it and what it will not cover.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the marginal contribution is the data-shape caveat: both windows are N calendar days in the property's time zone, they do not overlap, and the current window ends today while today is still filling in. That partial-day warning is exactly the kind of gotcha annotations cannot express and that would otherwise cause an agent to misread a low days=1 diff. It stops short of noting row caps or response shape, but an output schema exists to cover the latter.

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?

Three short sentences, leading with the one-line definition before the mechanics and the caveat. The parenthetical example (days=1 is today vs yesterday) is the most valuable sentence and is not padded with restated parameter names.

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?

For a 5-parameter, 1-required tool with a full schema, complete parameter descriptions, an output schema, and read-only annotations, the description supplies the one thing structured fields cannot: the time-zone/non-overlap/partial-day-window behavior. It could go further by distinguishing itself from `compare_periods` or noting row-limit behavior, but nothing needed to invoke it correctly is missing.

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 would be 3; the description earns the bump by explaining the semantics the schema only gestures at — the windows are calendar days in the property's time zone, non-overlapping, and anchored to today, which explains why days=1 compares today against yesterday rather than two completed days. It adds no guidance on `limit` or `by_dimension`, but those are fully described in the schema.

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?

"Diff the last N days vs the prior N days" gives a specific verb (diff) and resource (the two adjacent windows of GA4 data), and the WoW/MoM phrasing tells an agent the intended granularity. It does not differentiate from the sibling `compare_periods`, which sounds near-identical, so an agent cannot resolve GA4-vs-other-source selection from the description alone.

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?

Usage is implied rather than stated: the WoW/MoM/day-over-day framing signals when a period comparison is the right tool, but there is no explicit "use this instead of ga4_overview when..." routing and no exclusion against the sibling `compare_periods`. The agent must infer usage from examples.

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

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

Annotations already cover the safety profile (readOnly, openWorld, non-destructive), and the description goes well beyond them: it discloses the sort order (conversions desc), the currency/time-zone envelope, and the fact that the day window is cut in the property's own zone rather than UTC. The explanation of why the bare-row format was abandoned is exactly the kind of trap an agent would otherwise fall into.

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?

It is front-loaded — purpose, then return shape, then the gotcha — which is the right ordering. But the 11,611 key-event anecdote and the paragraph about the old bare-row format are long relative to the decision they support, and some of the return-field enumeration is redundant with the output schema.

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?

For a read-only analytics tool with a full output schema, this covers everything an agent needs to call it and to interpret the result honestly. The only excess is that it re-explains return fields the output schema already declares, rather than spending that space on sibling routing.

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, but the description adds real meaning to `days` by explaining that the lookback is computed in the property's time zone — a semantic an agent cannot get from 'lookback window, default 28'. `limit` gets no such treatment, which is why this is not a 5.

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 opening sentence names a specific resource pair (conversions and conversion-attributable revenue) and a specific dimension (traffic source), which is enough to distinguish it from the session-oriented ga4_traffic_sources. It stops short of naming that sibling explicitly, so the differentiation is inferred rather than stated.

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?

Strong in-tool guidance: read the rate from `sessionKeyEventRate` and never divide conversions by sessions, and never quote the overall rate without the `key_events` breakdown beside it. It also directs shops toward `transactions`/`purchaseRevenue`. What it lacks is routing guidance — nothing says when to pick this over ga4_traffic_sources or ga4_events_by_name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior detail — the returned field list, units (engagementRate 0..1, duration in seconds), and sort order (engaged sessions desc) — but says nothing about pagination, empty-result behavior, or rate limits.

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?

Front-loaded with the purpose, then the use case, then the return shape and sort order — a logical progression with little waste. One minor redundancy is enumerating return fields when an output schema already exists.

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?

For a simple 3-parameter read tool with full schema coverage and an output schema, the description is adequate but leaves gaps: which property_id values are valid and where to get them, what happens with zero-traffic pages, and how it differs from ga4_top_pages. The listed return fields partially duplicate the output 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 days, limit, and property_id are already documented in the schema with defaults. The description adds no additional meaning about these parameters (e.g., whether days is a rolling window, or how limit interacts with sorting), so the baseline 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?

States a specific verb-like outcome ('per-page engagement metrics') tied to a clear resource (pages), so an agent knows it returns page-level engagement rather than traffic. It does not, however, explicitly distinguish itself from close siblings such as ga4_top_pages or ga4_events_by_name, which an agent would have to infer.

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 line 'Useful for spotting pages that bring traffic but don't keep users' gives an implied use case but no explicit when-to-use vs. when-to-use-an-alternative guidance. There is no mention of the sibling tools (ga4_top_pages, ga4_compare_periods) or of prerequisites such as resolving property_id via list_ga4_properties.

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

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

The annotations already establish that this is a read-only, open-world, non-destructive query. The description adds useful behavior beyond that by explaining the default output shape (one row per event_name with eventCount and totalUsers), optional pagePath slicing, and filtering to an event family. It does not cover authentication, quota, sampling, or error behavior, but the annotations and output schema lower the burden.

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 front-loads the purpose and default output, then explains optional parameters with compact examples. There is no filler, and the line breaks make it easy to scan.

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?

For a read-only GA4 event query with an output schema and full parameter descriptions, the description covers the key selection and invocation details: scope, default aggregation, page slicing, and event filtering. The main missing piece is explicit sibling routing or when-not-to-use guidance.

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, but the description adds practical meaning for group_by_page and event_name_filter beyond the schema text. The homepage scroll-depth example clarifies how group_by_page is useful, and the filter description clarifies focusing on a single event family, though days, limit, and property_id are left to the schema.

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: an event-level breakdown over the last N days, with concrete event use cases such as scroll depth, outbound clicks, file downloads, and custom events. It is clearly about GA4 event data, but it does not explicitly distinguish itself from siblings like ga4_engagement, ga4_top_pages, or ga4_overview.

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?

It gives clear usage contexts, including scroll depth, outbound clicks, downloads, and custom events, and explains when to use group_by_page and event_name_filter. However, it does not state when not to use the tool or name sibling alternatives for page-level or engagement summaries.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real interpretive value by specifying units and ranges (bounceRate 0..1, averageSessionDuration in seconds, engagementRate 0..1). It says nothing about auth, quota/rate limits, or how missing property access is surfaced, which matters for an open-world external API.

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?

Two short sentences, front-loaded with the core purpose and followed by the concrete metric inventory. Every sentence carries information, though the metric list partially duplicates what the output schema already conveys.

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?

For a two-parameter read-only snapshot tool with an output schema and annotations already in place, the description supplies enough to select and call it correctly. Only the routing relationship to the other GA4 siblings is left implicit.

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 both parameters are fully documented there, including the 1-365 range and the accepted property-id forms. The description's "last N days" only loosely echoes the days parameter and adds no syntax or constraint beyond the schema, so the baseline 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?

"High-level GA4 snapshot for a property over the last N days" gives a concrete resource (GA4 property), a scope (last N days), and a mode (headline/overview). Listing the exact metrics makes it distinguishable from deeper siblings like ga4_top_pages or ga4_engagement, though it never names an alternative explicitly.

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 phrase "headline metrics SEOs and product folks check first" implies this is the entry-point/broad-look tool, and the metric list tells the agent what questions it can answer. However, there is no explicit "use this instead of X when Y" guidance nor any stated preconditions such as needing a property_id from list_ga4_properties.

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

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

Annotations already establish that this is a read-only, open-world, non-destructive operation. The description adds the critical behavioral detail that results cover only the last 30 minutes, but it says nothing about freshness, quota/rate-limit behavior, or property access requirements.

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?

It is a single, front-loaded sentence with zero unnecessary wording. The time window and aggregation dimension are both stated compactly.

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?

For a simple two-parameter tool with full schema coverage, annotations, and an output schema, the description is nearly complete. It covers the key realtime scope and dimension breakdown, though it could mention quota or freshness caveats relevant to realtime reporting.

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 schema already documents both property_id and the valid dimension values. The description reinforces that dimension controls the breakdown, but adds no syntax or selection guidance beyond the schema.

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 precise metric and scope: active users in the last 30 minutes, broken down by dimension. This distinguishes it from historical GA4 siblings such as ga4_overview and ga4_user_demographics by its realtime 30-minute window.

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?

Usage is implied by the 30-minute realtime scope, but the description gives no explicit when-to-use guidance, exclusions, or named alternatives. An agent can infer realtime use but must rely on the tool name and sibling context for routing.

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

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

Annotations only declare readOnly/openWorld safety, so the description carries the semantic burden and does: it discloses that a session is counted once per page visited, that rows sum to more than total sessions, and that activeUsers repeat across rows. This is precisely the non-obvious behavior that would otherwise cause an agent to misreport metrics.

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?

Front-loads the core definition, then layers the double-counting caveat and the two sibling alternatives. Every sentence adds decision-relevant information; nothing is restated from the schema or 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?

An output schema exists, yet the description still names the returned metrics and warns about their cross-row duplication, which is the one thing the output schema cannot convey. Combined with aggregation advice and the GSC alternative, nothing needed to call or interpret this correctly is missing.

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 days/limit/property_id are already documented with ranges and defaults. The description only echoes 'over the last N days' without adding format or interpretation guidance, so it neither compensates nor adds much beyond the schema.

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?

Names a specific verb and resource ('Top pages by sessions over the last N days (GA4 pagePath)') and immediately corrects the misleading title by stating 'These are not landing pages'. An agent can distinguish this from ga4_overview or correlate_gsc_to_ga4 without opening any schema.

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?

Gives explicit routing rules: 'Take totals from ga4_overview' and 'To compare pages with Search Console clicks, use correlate_gsc_to_ga4'. It also states the condition that makes this tool wrong for landing-page questions, which is exactly the disambiguation an agent needs.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered elsewhere. The description adds nothing on top: no note on rate limits, quota cost, data freshness/latency, or what the default 28-day window implies about results.

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?

It is a single short fragment with nothing wasted, which is structurally clean. But its brevity comes from omission rather than compression — there is no front-loaded verb or scope statement to orient the agent.

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?

An output schema exists, so return values need no explanation, and the parameter schema is fully documented. Still, for a report tool in a large sibling set, the description omits all routing information and any behavioral context, leaving the agent to rely entirely on structured fields.

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 every parameter (days, limit, dimension with its channel/source/medium/campaign mapping, property_id) is documented inline in the schema. The description only restates the three dimension values already enumerated there, adding no new meaning; baseline 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 fragment 'Traffic breakdown by acquisition channel / source / medium' identifies the resource (traffic) and the breakdown dimensions, so an agent can infer the report subject. However, it is not a verb-led statement and gives no hint at how this differs from siblings such as ga4_conversions_by_source or ga4_overview, both of which also return source-segmented traffic.

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?

There is no when-to-use guidance, no mention of prerequisites such as needing a valid GA4 property id, and no naming of alternatives. An agent must guess whether this or ga4_overview / ga4_conversions_by_source is the right call for a given question.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds genuine behavioral context about aggregation semantics — 'top countries by activeUsers', deviceCategory bucketing, 'top browsers' — which annotations cannot convey. It does not mention cost, quotas, or how ranking/cutoffs work, so this is additive but not rich.

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?

It is short and front-loaded, with the scope in line one and the return slices as a scannable list. The only slight waste is spending description space enumerating return fields when an output schema already exists.

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?

For a three-parameter read-only aggregate with an output schema, the description gives enough to know roughly what comes back, and return values need not be re-explained. However, with 0% schema coverage it should clarify property_id's role and the limit behavior, and it gives no guidance on choosing this tool among many GA4 siblings.

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 0%, so the description must carry parameter meaning, and it only partially does: 'last N days' clarifies the days parameter's window. The 'limit' parameter (presumably top-N per slice) and the required property_id are never mentioned, leaving two of three parameters unexplained in both schema and description.

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 names a concrete resource (audience breakdown) and enumerates the three output slices (by_country, by_device, by_browser), which makes it distinguishable from sibling GA4 tools like ga4_overview or ga4_traffic_sources. It falls short of a full verb+scope statement because it never says explicitly that this reports GA4 demographic/technology dimensions of active users.

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?

There is no when-to-use guidance at all: nothing says to pick this over ga4_overview, ga4_engagement, or ga4_traffic_sources, nor what question it answers. The reader must infer usage entirely from the returned slices.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds one useful behavioral fact — the sample is capped at 10 — but says nothing about what the time window means, whether the cap silently truncates a larger requested sample_size, or how the counts are scoped.

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?

It is very short and front-loads the key constraint, with no wasted words, but the telegraphic fragment style ('Top N pages inspected') is cryptic rather than dense — the brevity comes at the cost of comprehension.

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?

An output schema exists, so return values need not be described, but for a tool with a required site_url, a date window, and a language parameter at 0% schema coverage, the definition leaves too much for the agent to infer.

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 0% for four parameters, so the description must compensate. It only partially does: 'Top N' hints at sample_size and the cap clarifies its ceiling, but site_url (required), days, and language_code are left entirely unexplained.

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 fragments 'Top N pages inspected; verdict + coverageState counts' convey that this aggregates index-coverage statuses over a sample of pages, but there is no explicit verb+resource statement and no differentiation from siblings like inspect_url, batch_inspect_urls, or archive_status.

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?

There is no when-to-use guidance, no mention of prerequisites (site verification/property access), and no pointer to the per-URL alternatives for drilling into individual pages.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description adds real value by disclosing that results always come from the live Google API (relevant given the sibling search_analytics_archive) and by explaining anonymized-query accounting that makes totals diverge from row sums. It does not cover auth scope or rate limits, keeping it short of a 5.

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?

Front-loaded with the core answer (one total, four metrics) and then the reconciliation caveats in order of likely confusion. The multi-sentence explanation of page-level double counting is a bit long, but it prevents a concrete misreading rather than padding.

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?

An output schema exists, so return shape needn't be restated; the description instead spends its budget on the things an agent would otherwise get wrong — filter semantics, anonymized traffic, and why totals won't equal summed rows. Nothing needed to call it correctly is missing.

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 earns a point by explaining dimension_filter_groups semantics beyond the schema — an inline worked page-filter example and the rule that a query filter never matches anonymized queries. Date, site_url and search_type are left to the schema, which is reasonable given coverage.

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?

States a specific resource (property-wide totals) and enumerates the exact metrics returned (clicks, impressions, CTR, average position), then explicitly says there is no breakdown by query or page. That contrast with search_analytics_query lets an agent distinguish it from the sibling without opening the schema.

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?

Explicitly frames when to use it (property-wide total) versus the alternative (rows from search_analytics_query), and explains the conditions under which the numbers will and will not reconcile with that tool. The filtered case is covered with a concrete example, leaving little to inference.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. Beyond that the description adds nothing: no note that results come from Search Console data, no indication of what happens on missing date bounds, and no rate-limit or volume expectations for a tool that returns query-level rows.

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 single sentence is front-loaded and free of padding, which is good. But brevity here comes from omission rather than economy – the fragment is underspecified for a five-parameter tool rather than deliberately terse.

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?

An output schema exists, so return-value explanation is not required. Still, for a five-parameter analytics tool with zero schema documentation, the description leaves required inputs, date handling, and row limiting entirely unexplained, which is not sufficient for correct invocation.

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 0% across five parameters, so the description carries the full burden and largely fails. It implies page_url but says nothing about site_url (required), start_date/end_date defaults of null, or what row_limit=100 means for truncation – the agent has no way to know it may be receiving a capped result set.

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?

"Queries that drove traffic to a specific page" identifies the resource (search queries) and the scoping dimension (one page), so an agent can tell it is page-level rather than site-level. However, it is a noun fragment with no verb and never names the sibling search_analytics_query as the unfiltered alternative, so differentiation is left to inference.

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?

There is no when-to-use guidance, no exclusion, and no mention of the obvious alternative in the sibling list (search_analytics_query, compare_periods). The agent must guess whether this tool needs a prior list_sites call or how it relates to other search-analytics tools.

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

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

The definition relies heavily on annotations (readOnlyHint: true, destructiveHint: false) for behavioral safety context. The description adds no additional traits, which is acceptable given the richness of the structured hints.

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 definition is a single, efficient sentence. Every word contributes directly to defining the tool's function and scope, requiring no unnecessary elaboration.

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 low complexity (one parameter) and high fidelity of the input schema and safety annotations, the description is complete in defining the basic operational contract of 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?

Although schema coverage is 100%, the description adds critical semantic value by specifying that the 'site_url' must be exactly as returned by 'list_sites,' providing a necessary technical constraint for correct invocation.

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 defines the action ('Get details') and the resource ('Search Console property'). It is specific, though it does not differentiate itself from other 'get' or 'list' type sibling tools.

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 offers no guidance on when to use this tool relative to other available endpoints, nor does it describe any prerequisites or limitations on its application.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that: it does not say what kind of details are returned, whether the call is scoped to a verified property, or how it behaves for sitemaps that exist but were never fetched.

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?

A single short sentence that is front-loaded and waste-free, but the brevity comes at the cost of information rather than being earned through efficiency. There is no structure beyond the bare statement of purpose.

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?

An output schema exists, so return values need not be explained, but the two required inputs carry no semantics anywhere in the definition. For a two-parameter lookup tool with zero schema coverage, the description should at minimum explain what feedpath and site_url must contain to avoid failed calls.

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 0%, so both required parameters are undocumented in the schema, and the description does not compensate. In particular, feedpath is ambiguous (full sitemap URL versus path? relative or absolute?) and site_url is presented without saying whether it must match a verified Search Console property.

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?

States a specific verb (get) and resource (details of a single sitemap), and the word "single" implicitly contrasts it with the sibling list_sitemaps that returns many. The only gap is that "details" is left undefined, so the agent knows what object it targets but not what information it returns.

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?

There is no when-to-use guidance, no prerequisite (e.g., needing site_url/feedpath obtained from list_sitemaps), and no note on failure behavior for unknown sitemaps. The agent must infer usage purely from the name and from the existence of list_sitemaps in the sibling set.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered; the description usefully adds result shape ('one row per date, sorted oldest-to-newest') and a retention claim. Beyond that it says nothing about rate limits, quota cost of long ranges, or empty-result behavior for queries with no history. Decent additive value, but thin for a tool whose main selling point is deep historical pulls.

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?

Front-loaded with the return payload, then scope, then shape, then an example — three short blocks with no filler. The line breaks read a bit like stream-of-consciousness, but every sentence carries information.

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?

With an output schema present, the description rightly doesn't need to enumerate return fields, and it covers scope and ordering. The remaining hole is date-parameter format/interpretation, which is missing from both schema and description for a tool that depends entirely on arbitrary ranges.

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 50%: 'query' and 'site_url' are documented in the schema (including the % partial-match trick), but start_date and end_date have no description anywhere and the description does not supply a date format or timezone. The description reinforces that the query is singular and the range is unbounded, which adds modest meaning, but the two date params remain undocumented.

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?

States a specific resource and payload: daily clicks/impressions/CTR/position for a single query, plus the differentiator 'Goes back to whenever your archive started (no 16-month limit)'. That scope statement separates it from the standard-GSC-window siblings, though it never names the sibling that carries the 16-month limit (e.g. search_analytics_query).

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?

Gives clear triggering context ('over any date range', 'no 16-month limit') and a concrete example use case ('show me how workshop has been doing all year'), which tells an agent when this tool is the right pick over a shorter-window query. It stops short of naming alternatives or stating when not to use it.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful quota limits (~600/min/site, 2000/day/site) that the annotations do not carry, but leaves out what the inspection returns behaviorally and any auth/site-verification requirements.

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?

Two short sentences, purpose front-loaded and quota secondary, with no filler. It is efficient, though its terseness contributes to the parameter gaps noted above.

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 output schema exists, so return values need not be explained, but for a tool with two required string parameters and zero schema coverage the description should clarify the site_url/inspection_url relationship. As written, an agent cannot confidently populate two of three parameters from this text.

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 0% for all three parameters; site_url, inspection_url, and language_code carry no descriptions and no enums. The description mentions only "a single URL," giving no guidance on how site_url relates to inspection_url (same property vs. arbitrary URL) or what language_code affects.

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?

States a specific verb and resource ("Inspect a single URL's status"), and the word "single" quietly separates it from the sibling batch_inspect_urls. What "status" actually means (index status vs. HTTP reachability) is not specified, which keeps it from a 5.

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?

Usage is only implied: "single URL" suggests using batch_inspect_urls for many URLs and this tool for one-off checks. It never names the alternative or states prerequisites, so the agent must infer routing from sibling names alone.

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

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

Annotations already declare readOnlyHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description still adds real behavior: the call returns the full account+property tree in a single round-trip, and the properties list is empty when the user has no GA4 (or only Universal Analytics). The inline sample payload is somewhat redundant with the existing output schema, which slightly dilutes the added value.

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?

Front-loaded with the prerequisite, then the return contract, then the empty-result edge case. The multi-line JSON block is the largest chunk and duplicates the output schema, so a sentence describing the tree shape would have been leaner, but nothing is truly wasted.

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?

For a zero-parameter discovery tool with annotations and an output schema, everything an agent needs is present: when to call it, why (to obtain property_id), what comes back, and how the empty case reads. No open questions remain before invoking it.

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 tool takes zero parameters, so there is no parameter semantics to explain and the baseline applies. The description correctly spends no words on arguments and instead spends them on prerequisites and return shape.

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?

States a specific verb and resource ('List every Google Analytics 4 account + property') and scopes it to what the user can access. It is immediately distinguishable from the ga4_* siblings because it declares itself the discovery step that produces the property_id those tools require.

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?

Explicit precondition: 'Always call this first when working with GA4 - the AI needs a property_id to pass to every other ga4_* tool.' That is both a when-to-use and a routing rule to the sibling family, with no ambiguity left to infer.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered elsewhere. The description adds nothing beyond that — it does not say whether results include sitemap indexes, whether the call is paginated, or what happens when a property has no sitemaps.

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?

A single short sentence with zero padding, so there is nothing wasteful. However, brevity here comes from under-specification rather than discipline; the sentence is too thin for a two-parameter tool with an undocumented optional argument.

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?

An output schema exists, so return values need not be described. Still, for a tool whose optional sitemap_index parameter changes what is listed, and whose required site_url has a strict format, the definition leaves too much to guesswork.

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 0%, so the description must compensate and does not. It never explains the site_url format (property URL vs domain property) or what sitemap_index is for — likely to list the children of a sitemap index — which is a meaningful behavioral distinction for this tool.

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 names a specific verb and resource ("List all sitemaps") and scopes it to a property, so an agent knows what it returns. It does not distinguish itself from the sibling get_sitemap_details, leaving the list-vs-detail split implicit.

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?

There is no when-to-use guidance, no mention of when to prefer get_sitemap_details, and no prerequisites such as needing a verified Search Console property. The agent must infer routing from the tool name alone.

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

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

Annotations already declare read-only, non-destructive, open-world, but the description adds genuinely non-obvious behavior: results are filtered by a user-managed allowlist at app.gscpap.com, so Google-permitted but disabled sites are invisible and unqueryable. It also discloses the exact shape of each entry and the four permissionLevel values, going beyond what the annotations 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?

Front-loaded with the core purpose, then scope/filtering, then return shape, then sibling routing — a sensible order. The closing paragraph on GA4-vs-GSC question classes is slightly long for a list tool, though it does earn its place by preventing misrouting to the GA4 siblings.

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?

For a zero-parameter, first-call discovery tool, everything needed is present: authorization scope, allowlist filtering semantics, returned fields, and routing to the GA4 counterpart. An output schema exists, and the description appropriately confirms rather than belabors return values.

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 tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. It uses the space instead to document the returned fields (siteUrl, permissionLevel) rather than parameter meaning.

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 first sentence gives a precise verb and resource: 'List Google Search Console properties accessible to the authenticated user.' It also scopes the result to MCP-authorized properties, which distinguishes it from siblings that read GSC data (get_site_details, search_analytics_query) and from list_ga4_properties.

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?

It explicitly states the entry point ('the tool every client calls first') and names the alternative plus the condition that selects it: 'Call list_ga4_properties for those' (GA4 properties). It even sketches the question classes each source answers (sessions/conversions vs impressions/clicks/position) and points to correlate_gsc_to_ga4 for joins.

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

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

Well beyond the annotations, which only declare readOnly/openWorld/non-destructive, the description discloses the 28-day aggregation window, the 75th-percentile basis, rating buckets, the URL-level vs origin-level fallback for low-traffic URLs, and caching behavior. This is unusually complete, with the only gap being no mention of error behavior for URLs absent from CrUX entirely.

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?

Front-loaded with the one-line purpose, then organized into scannable paragraphs covering return values, the origin fallback caveat, and cache sharing. Every sentence carries actionable information 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?

An output schema exists, so return values need not be re-explained, and the description still adds the interpretive layer (percentile, rating buckets, fallback). For a two-parameter read tool, nothing an agent needs to call it correctly is missing.

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% and both parameters are documented, so the schema carries the semantics. The description reinforces the "public URL" constraint and clarifies that results are split at URL and origin level, but it never explains the strategy parameter's device-class effect beyond what the schema already says.

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?

States a specific verb and resource ("Get Chrome User Experience Report (CrUX) field data for a public URL") and immediately scopes it to real-user metrics over 28 days. It also distinguishes itself from the lab-measurement sibling by contrasting real-user data against "a single Lighthouse lab run."

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?

Explicitly frames the selection condition: use this to answer "what do my actual users see?" rather than lab data, which implicitly routes the agent away from pagespeed_insights for field metrics. It also notes the shared 24h cache, telling the agent that calling both tools is cheap rather than redundant.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely non-obvious behavior beyond them: a 24-hour server-side cache keyed on (url, strategy) with 'free + instant' repeat calls, and a cap of the top 8 opportunities ranked by potential savings. It does not mention any API key, quota, or rate-limit behavior for uncached runs.

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?

Front-loaded with the verb and target, then structured into returns / caching / companion-tool sections. Slightly redundant to enumerate scores and metrics since an output schema exists, but the enumeration is compact and the 'top 8' truncation note is worth its space.

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?

For a two-parameter read-only audit tool with a full output schema and safety annotations, the description covers the remaining gaps an agent needs: which data flavor it returns, caching semantics affecting repeat cost, and the truncation of opportunities. Nothing required to invoke it correctly is missing.

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 `strategy` parameter already documents mobile vs desktop throttling profiles in detail, including the Moto G4-class CPU emulation. The description adds only the cache-key framing '(url, strategy)', which is marginal semantic value over the schema, so 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?

States a specific verb and resource ('Run a Google PageSpeed Insights (Lighthouse) audit on a public URL') and immediately scopes what kind of data it produces (lab data) versus the field-data sibling. An agent can distinguish it from pagespeed_field_data without opening either schema.

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?

Explicitly names the companion tool `pagespeed_field_data` and states what it returns instead ('real-user CrUX data from the same underlying call'), so the lab-vs-field routing decision is clear. It also flags a hard constraint ('localhost / staging URLs won't work'). It does not address other plausible siblings such as batch_inspect_urls for multi-URL runs, so it stops short of full exclusion guidance.

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

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

Annotations only declare read-only, open-world, non-destructive behavior, so the description carries the substantive disclosure: anonymized queries are dropped by Google at query level causing 30-40% lower clicks, the response carries a `source` field of 'google' vs archive, and older archive ranges include a `note` about excluded anonymized traffic. This is exactly the kind of caveat an agent needs to interpret results correctly.

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 opening lines front-load purpose and return shape, and the bulleted enumeration of the three sourcing cases is well structured. It is on the long side with some connective prose ('This tool handles that as follows') that could be trimmed, but nearly every sentence carries decision-relevant information.

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?

For a tool with an output schema, seven parameters, and a subtle data-provenance problem, the definition covers the sourcing rules, the freshness tradeoff, and the alternative tool. Nothing needed to call it or to interpret its results is missing.

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 goes beyond it by explaining that the 'query' dimension or a query filter changes the data source, and that no dimensions or only 'date' yields totals including anonymized traffic. It does not add anything about row_limit/start_row pagination semantics, so it falls short of a full 5.

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?

States a specific verb and resource ('Query the Personal Archive'), names the scope beyond Google's 16-month limit, and specifies that it returns aggregated rows by requested dimensions with impression-weighted position. It is clearly differentiated from the sibling search_analytics_query, which it names directly.

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?

Explicit routing rules are given: use for historical/trend questions where freshness is not critical, and use search_analytics_query for the last 3 days. It also enumerates exactly which requests are served from archived rows, which from archived daily totals, and which are proxied live to Google.

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

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

It adds substantial behavior beyond the annotations: the read-through cache path, zero-GSC-quota archive reads, the `_source` response field, anonymized-query limitations, and the `note` added for older ranges. These details are exactly the kind of operational context an agent needs for this read-only but open-world query tool.

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 purpose and cache behavior, and the anonymized-query caveat is relevant rather than filler. It is somewhat long, but the length is justified by the complexity of the archive-versus-Google routing behavior.

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?

For a 9-parameter read-only query tool with no output schema, the description covers the key return hints (`_source`, `note`) and the main caveats around anonymized traffic and archive coverage. It does not describe every response field, but it is complete enough to call 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 coverage is 100%, so the baseline is 3. The description adds meaningful semantics for parameters like data_state=final, search_type=web, and dimensions/query filters by linking them to archive eligibility and Google fallback behavior.

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: 'Query Search Console analytics for a property.' It also explains the archive-versus-Google fetch behavior, but it does not explicitly name or differentiate itself from sibling tools such as search_analytics_archive.

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 explains conditions that determine whether the request is served from the archive or Google, including date range, search_type, data_state, and dimensions. However, it gives no explicit when-to-use guidance versus sibling tools like search_analytics_archive or get_search_by_page_query.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful scope disclosures (one query per call, results capped at the top 10, your-domain-centric view), but says nothing about cost, rate limits, geographic sensitivity of live SERP data, or what a miss looks like. With annotations carrying the safety burden, this is adequate but thin.

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?

Two short sentences, front-loaded with the core capability and followed by the workflow hint. Nothing is padded, though the GSC aside is informal and slightly loose for a tool definition.

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?

An output schema exists, so return values need not be described, and the read-only nature is handled by annotations. What is missing is anything about the three undocumented optional parameters and their defaults, which for a geo-sensitive SERP tool is the main thing an agent could get wrong.

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 40%, so the description needs to compensate, and it does not: device, country (default 'tr') and language all go unexplained anywhere. Those defaults materially change SERP results, and a 'tr' country default is surprising enough that silence is a real gap. The description adds only that a single query is accepted, which the schema already implies.

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?

States a specific verb and resource: 'find where YOUR domain ranks plus the full top-10 competitor list' for a single query. That is more specific than the sibling serp_top_results (which presumably just lists results) because it adds the my_domain rank lookup. However, it never names a sibling tool, so the distinction from serp_top_results or serp_features_audit has to be inferred.

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?

Gives an explicit workflow: pull low-CTR queries from GSC (find_quick_wins), then call this to see who outranks you. That is real when-to-use guidance tied to a sibling tool. It does not state when NOT to use this versus serp_top_results, and there is no prerequisite or rate/cost note, which keeps it below a 5.

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

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

Annotations only declare read-only, open-world, non-destructive; the description adds genuinely new behavioral facts the agent could not infer: ai_overview is always null because the provider never returns it, and for some countries (e.g. 'tr') the provider returns organic-only so feature_data_available is false and nulls mean unknown, not absent. It even gives a remediation (retry with country="us").

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 purpose and the trigger question are front-loaded in the first two sentences, then the caveats are isolated into a short bulleted list. Every sentence carries operational information — no restating of the title or filler — and the most decision-relevant caveat (null means unknown) is bolded in substance by placement.

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?

An output schema exists, so return-value shape need not be explained, and the description covers the two failure modes that would otherwise cause misreads of null fields. What is missing for a four-parameter audit tool is any statement about device/language behavior or cost/latency implications beyond the 25-query cap.

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 only 25% (only 'queries' is documented, including the max-25 cost bound), so the description must carry the rest. It partially does: it explains the consequence of the country parameter (the 'tr' organic-only case and the country="us" workaround). However, device and language semantics are never addressed, leaving two of four parameters with no guidance in either structured field or description.

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 first sentence states a specific verb and resource: fetch the SERP for a list of queries and report which click-eating features are present. It names the concrete features (Featured Snippet, Map Pack, People Also Ask) and explicitly distinguishes itself from find_ai_overview_suspects and ga4_ai_traffic, so an agent can separate it from sibling SERP/AI tools without opening a schema.

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?

It gives a concrete trigger scenario ('why is my CTR so low at position 3?') plus explicit routing away from this tool: use find_ai_overview_suspects for suspected AI Overview queries and ga4_ai_traffic for AI assistant traffic. That is when-to-use, when-not-to-use, and named alternatives in one compact block.

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

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

It discloses critical behavioral edge cases not in the schema, such as AI Overviews always being null and country-specific limitations (e.g., 'tr') regarding feature availability and the use of 'feature_data_available' flag.

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 highly informative and well-structured, leading with capabilities before detailing constraints. It is slightly verbose, but the density of information justifies the slight reduction from 5.

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 complexity of SERPs and the presence of localized behavior, the description is exceptionally complete. It addresses output limitations (AI Overview) and regional variations that an agent must know to use the tool effectively.

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?

Although schema coverage is 100%, the description adds vital context regarding the 'country' parameter, advising the user to select the country corresponding to their actual user base due to SERP differences.

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 the tool retrieves live SERPs and goes beyond simple link retrieval by auditing specific SERP features like Knowledge Panels and Map Packs.

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?

It provides an explicit use case scenario: use the tool when GSC position data is insufficient and the agent needs context on competitor presence or feature interference.

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