Metrinel

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

Annotations already declare this as read-only, non-destructive, and open-world, so the description is not burdened with safety disclosure. It adds substantial behavioral context by enumerating the exact checks performed (smart bidding with conversions, CPC escalation, budget overruns, geo leakage, GA4 engagement, policy disapprovals, favicon-as-logo, informational search terms) and by explaining that findings are severity-ranked. It does not discuss runtime, rate limits, or failure modes when GA4 is missing, but the added detail is well beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the one-sentence purpose and then lists checks in a compact run-on list, followed by the breakdown coverage. It is longer than most tool descriptions, but the enumeration of checks is useful for deciding whether to call the tool. Minor improvement would be breaking the check list into structured bullets, but no sentence is clearly 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?

Given the complexity of a multi-check audit, the description covers what is inspected and what breakdowns accompany the findings, and an output schema exists so return values need not be fully restated. Remaining gaps are prerequisites (MCC access, GA4 linkage requirements) and the boundary against cheaper raw-data siblings like ads_query, which would make the definition fully self-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?

Schema description coverage is 100%, so the baseline is a 3, and the description adds little parameter-level meaning. It only implicitly connects GA4 to the 'low engagement' check, which the schema already covers with 'adds landing-quality checks,' and it never clarifies date_preset behavior or how login_customer_id affects account resolution.

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 (audit) and resource (one Google Ads campaign) plus a return contract: findings ranked by severity plus breakdowns. That is far more precise than sibling tools like ads_query or get_data, and an agent can distinguish this analytical tool from the raw-query siblings 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?

The audit scope implies when the tool is useful, but the description never states explicit when-to-use or when-not-to-use guidance. It also does not name alternatives such as ads_query for raw data or get_data for fetching campaign ids, and it gives no prerequisites like minimum date range or conversion volume needed for the bidding checks to be meaningful.

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 destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: the result includes both directly accessible accounts and, for MCC accounts, their direct client accounts, which tells the agent the result set can be broader than a 1:1 user mapping. It doesn't cover pagination, but an output schema exists to describe returns.

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, front-loaded with what the tool does, then what it returns, then when to call it. No sentence is filler and nothing 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?

Given zero parameters, an output schema, and full annotation coverage, the remaining burden is workflow positioning and result scope, both of which the description supplies. An agent can decide to call this first and pass the resulting ids onward without further help.

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. The description goes slightly beyond by introducing the customer_id and login_customer_id concepts the agent must carry forward to sibling tools, which is useful setup rather than parameter documentation.

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 the Google Ads accounts') plus the scope ('the user can access'). This is clearly distinguishable from siblings like ads_query or ads_audit_campaign, which operate on a single customer rather than enumerating accounts.

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 sequencing guidance ('Call this first') and explains why: downstream Google Ads tools need a customer_id, and manager-reached accounts need login_customer_id. This is exactly the when-and-why an agent needs to order calls correctly.

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 value by sketching the shape of each result row (type and select/filter/sort flags), but it says nothing about pagination, the default 300 / max 1000 cap, or cost/latency behavior – facts an agent would want before calling repeatedly.

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, zero filler. The output shape comes first and the usage cue second, which is the right ordering for a discovery tool an agent will chain into ads_query.

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 the annotations plus short description cover purpose and sequencing adequately for a simple two-parameter read tool. The only real gap is that the `limit` parameter has no stated purpose in either the schema or the description.

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%: `resource` is documented with concrete examples (campaign, ad_group, keyword_view, metrics, segments) while `limit` carries only default/min/max constraints and no prose. The description corroborates that the target is a GAQL resource but adds no meaning beyond the schema, and never mentions the limit parameter at all.

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 fields on a GAQL resource) and specifies exactly what is returned: type plus select/filter/sort capability. It explicitly positions itself relative to the sibling ads_query, so an agent can tell the two apart without reading 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?

"Use it before writing an `ads_query` on an unfamiliar resource" gives a clear triggering condition and names the dependent tool. It stops short of saying when not to bother (e.g. for well-known resources) or naming any alternative discovery tool, but the context is unambiguous.

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, and the description is consistent with them ("read-only"). Beyond the annotations it adds two genuinely useful behavioral facts: monetary fields ending in `_micros` are millionths of the account currency, and returned columns are camelCase (e.g. `metrics.costMicros`). It does not mention pagination behavior or result-size limits beyond the `limit` param.

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 action is front-loaded in the first sentence, followed by the scope list, then the two unit/naming conventions an agent must know to interpret results, then a single routing pointer. Every sentence carries information an agent needs; nothing is 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 need not be explained, and the description still supplies the column-casing convention and micros conversion rule that the output schema alone may not make obvious. Account scoping is covered by "against one Google Ads account"; only rate limits and result-size behavior are left unaddressed, which is a minor gap for a read-only query 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 100%, so all four parameters (customer_id, query, limit, login_customer_id) are already documented in the schema, and the description adds no per-parameter guidance such as when to set login_customer_id for MCC access. Baseline 3 applies when the schema carries the parameter burden.

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 read-only GAQL query against one Google Ads account") and then enumerates the resource families it reaches (campaigns, ad groups, keywords, search terms, conversions, budgets, change history). An agent can distinguish it from ads_list_fields (field discovery) and from the GA4 reporting siblings 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?

Gives a clear usage context (any report, one account) and explicitly routes field discovery to the sibling ads_list_fields, which is a real alternative-selection rule. It stops short of stating when to prefer ads_audit_campaign or a GA4 report over a raw GAQL query, so it is not a full when/when-not treatment.

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 destructiveHint=false, so the safety profile is covered. The description adds genuine behavior detail — that it reports access-denial reasons, connected Google services, and a disabled-resource count — but says nothing about cost, freshness, or whether the checks are live versus cached.

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 sentence that front-loads the primary subject (the signed-in user) and then enumerates the rest. The field list is long but each item is a meaningful discovery cue; it does not repeat the title or pad with 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?

With no parameters, an output schema present, and annotations covering safety, the remaining burden is just to tell an agent what the call is for — which it does. The only gap is the absence of any prerequisite or when-to-use framing.

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 nothing for the description to disambiguate and no risk of misuse. Baseline for a no-parameter tool 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?

"Show the signed-in user, their Metrinel plan and tier... whether access is allowed and why not" gives a concrete verb plus a specific set of account-level facts, which clearly separates it from the data-fetching siblings (ads_*, ga4_*, gsc_*). The distinction is inherent in the content rather than stated, so it falls short of explicit sibling differentiation.

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 usage context is only implied: an agent can infer this is the tool to call to check sign-in, plan limits, or whether access is blocked and why. There is no explicit "use this when..." statement, no exclusions, and no mention of prerequisites such as needing to be authenticated first.

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, non-destructive and open-world, so the safety profile is covered. The description adds that custom dimensions/metrics are included, which is useful scope information, but says nothing about result volume, pagination, or lookup cost against the live 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, purpose first, follow-up usage pointer second. No filler and nothing 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?

An output schema exists so return values need not be described, and annotations cover safety. The description covers purpose, custom-field scope and the next step in the workflow; only result-size/pagination hints are absent, which is minor here.

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 both property_id and the search filter are documented in the schema. The description adds nothing about the search parameter's matching behavior; 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?

Specific verb 'List' with the resource 'dimensions and metrics a GA4 property supports', plus the qualifier 'including its custom ones'. It is distinguishable from ga4_list_properties and list_fields, though it doesn't explicitly contrast against them.

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?

'Use it to find the exact API names for `ga4_run_report`' gives a clear when-to-use and ties the tool to its downstream consumer. There is no explicit when-not guidance, but the intended workflow is unambiguous.

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 cover the safety profile (read-only, non-destructive, open-world), so the description only needs to add context. It adds two useful facts: results are permission-scoped to what the user can access, and the key output is property_id consumed by downstream tools. It doesn't discuss volume, pagination, or empty-result behavior, which is a minor gap for a listing call.

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, front-loaded with the action, followed by the dependency hint. Every clause earns its place; nothing is repeated from the title or 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?

An output schema exists, so return shape need not be described, and annotations cover safety. The description is close to complete for a zero-parameter discovery tool, with only a small gap around what happens when the user has no GA4 access.

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?

There are zero parameters, so parameter semantics falls back to the baseline of 4. The description correctly implies the call scope (the current user's access) without inventing parameters that don't exist.

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 (List) and resource (Google Analytics 4 accounts and properties), plus a scope qualifier: only what the user can access. It also distinguishes itself from the other GA4 tools by naming its role as the prerequisite that yields property_id.

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?

"Call this first to get the property_id the other GA4 tools need" gives an explicit ordering rule and names the condition that selects it. No exclusions are needed because there is no competing sibling that lists 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds a genuinely useful behavioral constraint beyond those: only the realtime subset of dimensions and metrics is accepted, and the window is fixed at 30 minutes, both of which prevent failed calls. It omits anything about the limit ceiling or rate limiting.

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, no filler: the first states the action and time scope, the second states the supported-field restriction. Purpose is front-loaded and every sentence earns its place.

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 schema covers most parameters. However, for a tool whose main failure mode is passing unsupported dimension/metric names, the description should route the agent to ga4_list_dimensions_and_metrics and mention the limit parameter's role.

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 80%, so the schema already explains metrics, dimensions, property_id and dimension_filter with examples. The description adds only the constraint that names must come from the realtime subset, without pointing at ga4_list_dimensions_and_metrics as the way to discover valid names. Baseline 3 is appropriate.

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 ('Report activity on a GA4 property') plus a precise scope ('during the last 30 minutes'), which makes it distinguishable from ga4_run_report by time window. It does not name the historical sibling explicitly, so differentiation is implied 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?

The 30-minute window implies when this tool is appropriate (live/current activity), but there is no explicit when-not guidance or pointer to ga4_run_report for historical ranges. The agent must infer the routing from the realtime framing 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 adds genuinely useful behaviour not in the annotations: that `total_rows` reflects the full result size and that paging is done with `offset`. It says nothing about quota limits, invalid metric/dimension error behaviour, or comparison-period output shape.

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, front-loaded with the operation and its result shape, followed by the pagination caveat. No filler, no repetition of parameter names already in the 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?

With 12 parameters, an output schema and full annotations, the description covers the core call adequately. However, it omits two things an agent would benefit from: that metrics/dimensions must be valid GA4 API names discoverable via ga4_list_dimensions_and_metrics, and that property_id comes from ga4_list_properties (the schema mentions it, the description does not reinforce 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?

Schema description coverage is 83%, so the schema already documents dates, filters, order_bys and the comparison period in detail. The description only adds one piece of meaning beyond that: `total_rows` is the unpaged result size, which frames the offset parameter. Baseline 3 applies given the rich 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 ('Run a Google Analytics 4 report') and spells out the shape of the result (metrics broken down by dimensions over a date range, with filters, sorting and comparison). It does not explicitly contrast itself with ga4_run_realtime_report or ga4_list_dimensions_and_metrics, so sibling differentiation is left implicit through the date-range framing.

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: the date-range language hints this is the historical-report tool rather than the realtime one, and no prerequisites or exclusions are stated. Nothing tells the agent when to prefer this over ga4_run_realtime_report or get_data, and it does not point to ga4_list_dimensions_and_metrics for valid field names.

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, non-destructive, openWorld), so the bar is lower, and the description still adds real behavior: rows absent from a source return null, ratios are recomputed from totals rather than averaged, and Search Console data lags 2-3 days. The 15-minute cache is mentioned here but is already stated in the force_refresh schema text, so that sentence adds little; no disclosure of row limits or truncation behavior beyond the limit param.

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 preference/alternatives, then join examples, then edge-case caveats (nulls, ratio recomputation, lag). No redundant restatement of the schema; every sentence carries information an agent would otherwise have to infer.

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 explained, and the description still covers the non-obvious semantics an agent needs for a 9-parameter multi-source query: cross-source null filling, metric namespacing, join keys, and data freshness. Nothing critical for correct invocation appears 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 89%, so the schema already documents limit, dates, filters, order_by, and sources including the metric-prefixing rule. The description's added value is the join-key hint (campaign_id, landing_page), but it does not explain how sources' different date grains or the fields vocabulary interact when blending, leaving the schema to carry almost everything. Baseline 3 is appropriate for high 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 verb (query) and the exact resources (Google Ads, GA4, Search Console) plus the differentiator: one normalized field vocabulary across sources. That single clause separates it from ads_query, ga4_run_report, and gsc_search_analytics, which the sibling list confirms are per-source.

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 says 'Prefer this over the source-specific tools for reporting and for comparing sources', and gives two concrete join scenarios (campaign_id, landing_page) that define the cross-source case. The gap is that the alternatives are described generically as 'source-specific tools' rather than named, and no guidance is given for cases this tool does not cover, such as realtime reporting (ga4_run_realtime_report) or URL inspection.

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 (readOnlyHint=true, destructiveHint=false, openWorldHint=true), and the description adds genuine context beyond them: a concrete quota of roughly 2,000 inspections per property per day, which affects how an agent should batch calls. It does not mention auth/scopes or that inspection data can be stale for rarely-crawled URLs, so it falls short of fully rich disclosure.

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, both front-loaded and information-dense: the first states scope plus the exact data returned, the second states the operational limit. No filler or redundant restatement of the name or 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?

For a three-parameter read tool with a full schema and an output schema, the definition supplies what is needed to call it correctly: single-URL scope, the property-membership requirement, and the rate limit. The only gap is that it does not reference the output shape or handling of invalid/unindexed URLs, which the output schema largely covers.

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 each of the three parameters is already documented in the schema, including the exact property formats and the constraint that inspection_url must belong to the property. The description adds no parameter-level meaning beyond that, which is the expected baseline when the schema does the work.

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 ('Inspect one URL in Google's index') and enumerates the returned facets: coverage/indexing state, last crawl, canonical, robots.txt, mobile usability, and rich results. That enumeration effectively separates it from the sibling gsc_search_analytics, which deals with aggregate query data, though no sibling is named outright.

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: 'Inspect one URL' signals single-URL scope, and the quota note hints it is a limited, per-URL operation. There is no explicit when-to-use versus gsc_search_analytics or seo_opportunities, and no stated prerequisite that the property must be verified in Search Console.

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 this a read-only, non-destructive, open-world call, so the safety bar is low. The description adds context annotations cannot: the well-known Google limitation that indexed-URL counts are no longer reported, pre-empting an agent from expecting or fabricating indexation numbers. It does not discuss permissions or rate limits, but for a read-only list call that is a minor gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, both load-bearing: the first defines scope and payload, the second prevents a wrong expectation and names the alternative. Front-loaded with the capability and 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?

A one-parameter read-only tool with a full schema, existing annotations, and an output schema, so return structure and safety need not be re-explained. The description covers scope, payload, a known data limitation, and the fallback tool — everything an agent needs to call it 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 description coverage is 100% and the single `site_url` parameter already documents both the URL-prefix and sc-domain forms with examples. The description only repeats the concept of "a Search Console property" without adding format or validation detail, 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 and resource ("List the sitemaps submitted for a Search Console property") and scopes it to a single property. It also enumerates what is returned per entry (submission/download dates, errors, warnings, URL counts per content type), which tells an agent exactly what this produces versus gsc_list_sites or gsc_inspect_url.

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 routes page-level index questions to `gsc_inspect_url`, which is a genuine when-to-use-this-instead signal and also explains a missing data point. It does not mention gsc_list_sites as the way to discover the site_url value, and it gives no explicit exclusion for when sitemap data is irrelevant, so it stops short of full routing 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 already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that results are scoped to the user's accessible properties and include permission level, but says nothing about pagination, ordering, or behavior when no properties exist.

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 with zero filler, and the prerequisite instruction is front-loaded after the purpose statement. Every clause carries information an agent needs.

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, read-only listing tool with an output schema and full annotation coverage, the description supplies everything needed: what it returns, the permission-level detail, and its role as the entry point for the GSC tools.

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 nothing for the description to disambiguate; the baseline for a parameterless tool applies. The mention of `site_url` is about output, not input, and the output schema already covers return values.

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 the Search Console properties') plus the scope ('the user can access') and what is returned ('with their permission level'). The gsc_ prefix and 'Search Console' wording separate it cleanly from the analogous ga4_list_properties sibling.

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?

'Call this first to get the exact `site_url`' gives explicit sequencing guidance and the reason for it, which is exactly what an agent needs before invoking gsc_search_analytics or gsc_inspect_url. It stops short of naming those alternatives or stating when not to call it, so it 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 establish readOnly/openWorld/non-destructive, so the description's marginal value is in the operational details it does provide: sort order (clicks descending), pagination via start_row, and that ctr is a 0-1 fraction. It stops short of describing row-limit behavior or what happens when filters match nothing, but the added context is genuinely useful.

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, front-loaded with the resource and metrics, then paging and unit caveats. No filler and nothing repeated from the 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?

The output schema means return values need not be explained, and date-lag/format details live in the schema. However, for a 10-parameter tool with 60% coverage, the description leaves the aggregation and search-type semantics entirely to the schema, which is a noticeable gap 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?

With 60% schema coverage, several parameters (search_type, aggregation_type, data_state, row_limit) carry no meaning in the description at all. The description does clarify paging through start_row and the ctr unit, but it adds nothing about the aggregation/search-type choices that materially change results.

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 ("Search performance from Search Console") and enumerates the exact metrics returned (clicks, impressions, CTR, average position) plus the available groupings. This clearly separates it from sibling tools like gsc_inspect_url or gsc_list_sitemaps, which do not retrieve performance rows.

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: the mention of groupings and "Omit for site totals" hints at how to shape a request, but there is no explicit when-to-use versus alternatives (ga4_run_report, seo_opportunities) and no stated prerequisites beyond the schema's site_url format note. An agent must infer the selection criteria.

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, so safety is covered. The description adds a genuinely non-obvious behavioral guarantee beyond them: that field names are identical across sources, which tells the agent it can reuse one canonical field name regardless of the source it queries. It does not discuss paging or result size, but the presence of an output schema lowers that 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?

Two short sentences, front-loaded with the resource and scope, with no filler. The link to `get_data` appears in the first clause where the agent needs 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?

The tool is simple: one optional parameter, an output schema, and full annotation coverage. The description covers what is listed and the cross-source naming guarantee, which is sufficient. A brief hint that the `source` filter narrows the result would close the remaining gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single `source` parameter is documented in the schema itself as "Only fields available in this source." The description never mentions filtering by source, so it adds no meaning 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?

States a specific verb and resource ("List the normalized dimensions and metrics") and ties it to the sibling `get_data` it serves. The phrase "normalized" plus "Names are the same in every source" implicitly separates it from per-source listers like `ads_list_fields` and `ga4_list_dimensions_and_metrics`, but those alternatives are never named 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?

Usage is only implied: an agent can infer this is the discovery step before calling `get_data`. There is no explicit when-to-use statement, no exclusion telling the agent to prefer a source-specific lister in some cases, and no note on whether this should be called once or per session.

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, and the description adds real substance on top: it explains that the sections are derived heuristics and explicitly caveats that 'Expected CTR by position is a rough industry curve, not a promise,' which is important for interpreting the output. It stops short of noting cost/latency of pulling Ads and GA4 joins, but the interpretive caveat is more valuable than most.

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 is front-loaded in one sentence, followed by a scannable bulleted section list where each bullet defines one output category and its actionable interpretation. No filler sentences or restated tool name.

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 and high parameter coverage, the description covers what an agent needs: required site_url context is implied, optional joins are explained, and section contents are summarized. It does not address failure modes (missing Search Console access, mismatched Ads/GA4 accounts), which for a 7-parameter cross-service tool would be the remaining gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 86%, so the schema carries most parameter documentation. The description still adds consequence-level meaning by explaining what ga4_property_id and ads_customer_id enable ('possible savings', 'SEO work that would cut ad spend'), which is more than the terse 'Adds paid vs organic overlap' schema text conveys.

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 ('Find where organic search can grow'), names the primary data source (Search Console) and the optional joins (GA4, Google Ads). The four-section breakdown ('striking_distance', 'low_ctr', 'pages_without_clicks', 'paid_overlap') makes it clearly distinct from siblings like gsc_search_analytics or get_data, which return raw rows rather than curated opportunities.

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 clear context for when each mode applies: 'paid_overlap (with Google Ads)' and 'with their GA4 traffic when a property is given' tie the optional parameters to the additional sections they unlock. It does not explicitly say when to prefer this over gsc_search_analytics or get_data, so alternative routing is left implied rather than stated.

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