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

Annotations already cover read-only/idempotent safety, but the description goes far beyond them: failing or unconfigured platforms are isolated into their own block (partial), combined spend is null unless all currencies match with a combined_reason, ROAS is defined as total value / total spend, and cross-platform conversions overlap are explicitly not deduplicated. These are real behavioral traits an agent could not infer otherwise.

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 before the caveats, and nearly every clause carries distinct information. The long run-on sentences with stacked parentheses (combined_reason, currency rules, overlap warning) make it dense and harder to scan than it needs to be.

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 output schema, the description carries the full burden and does so: it names the returned metrics, explains the partial per-platform block structure, the combined aggregation and null semantics, and the cross-platform overlap caveat. Nothing essential for correct interpretation 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 the schema already documents start_date, end_date and client_id (including the empty-uses-only-client and per-platform timezone details). The description largely restates that scoping, adding only the 'never two clients mixed' constraint, which is marginal added value at this coverage level.

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 concrete verb and resource – pull Google Ads, Meta and OpenAI Ads totals side by side for one period – and enumerates the exact metrics returned (spend, impressions, clicks, conversions, conversion value, ROAS, currency, attribution windows, date range). This is clearly distinguishable from the single-platform siblings like gads_query, meta_insights and openai_ads_insights.

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 cross-platform scope and the 'one client only (client_id)' rule establish when this tool is the right choice, and the partial-failure note explains what happens when a platform is misconfigured. However, no sibling is named as an alternative and there is no explicit when-not-to-use guidance (e.g. use gads_query for per-campaign breakdowns).

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, idempotent, non-destructive, closed world), and the description adds real behavioral context beyond them: the entry types returned and the fact that secrets are masked. It does not say how entries are ordered or whether the journal is complete or windowed, which would have pushed it higher.

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 dense sentence that front-loads the verb and resource and puts the useful scoping detail (secrets masked) at the end. Nothing is redundant and nothing obvious 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?

For a three-parameter read tool with no output schema, the description does the key work of describing what comes back (plans, apply intents and results, rollbacks) and that secrets are redacted. It leaves out ordering and how much history exists, which an agent arguably needs to interpret results.

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 limit, plan_id, and client_id are already documented in the schema, including that client_id comes from clients_list and that an empty value uses the only client. The description adds only the vague phrase 'of a client' and no format or default semantics beyond 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?

The description gives a specific verb ('Read') and resource ('write journal of a client') and enumerates what the journal contains (plans, apply intents and results, rollbacks), which separates it from plan_list/plan_get/rollback_plan. It stops short of naming a sibling it is often confused with, so differentiation is implied rather than explicit.

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 for auditing past plan/apply/rollback activity. There is no explicit 'use this when...' guidance, no mention of when to prefer plan_get or rollback_plan, and no note on default ordering or scope of the journal.

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, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely non-obvious behavior: that secrets are reported only as booleans by kind and 'the values are never read out', which tells the agent the output is non-sensitive and shaped predictably.

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?

One dense but well-structured sentence that front-loads the core purpose ('Health of one client') and then enumerates the returned facets. No filler, though the nested parenthetical and clause stack require a re-read.

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 output schema and only one optional parameter, the description carries the return-shape burden and does so: it enumerates services, token/scope status, and the boolean secret map. It stops short of describing the response envelope or error semantics, but an agent has enough to call and interpret 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 100% — the single client_id parameter already documents 'Client id from clients_list; empty uses the only client'. The description adds nothing about the parameter, so the baseline 3 applies; it neither compensates for nor degrades existing 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?

The description names a specific resource and scope: health of ONE client, enumerated as configured services, Google token validity/scopes, and secret-storage booleans. The parenthetical '(like server_status)' positions it against the server-level sibling, giving partial sibling differentiation, though it doesn't explicitly contrast with client_profile or clients_list.

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 (check whether a client is healthy/configured) but there is no explicit when-to-use, when-not-to-use, or prerequisite statement. The only comparative cue is '(like server_status)', which hints at the relationship to the server-level tool but doesn't spell out which to pick when.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds a genuine extra disclosure that annotations do not carry: it returns configuration/account identifiers and 'Never a secret value', which tells the agent this tool is safe to surface in output.

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 that leads with the resource and then the payload, with no filler. The parenthetical platform list and the security note both earn their place, though the sentence is long enough that it reads as a dense enumeration rather than crisp guidance.

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 output schema, the description carries the burden of describing returns, and it does so concretely (label, sandbox flag, account ids, write policy). Safety is covered by annotations, so the only remaining gaps are minor: no error/absence behavior and no note on what an empty or unknown client_id yields.

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 client_id parameter is fully documented in the schema ('Client id from clients_list; empty uses the only client'). The description adds no parameter-level detail beyond this, 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?

The description names the resource precisely ('One client's profile') and enumerates its contents: label, sandbox flag, per-platform account ids, and per-platform write policy. The singular 'one client' implicitly contrasts with the plural clients_list sibling, so an agent can distinguish them, though the contrast is not stated 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?

The description lists what the profile contains but never states when to call it, when not to, or how it relates to siblings like clients_list or client_check. The only usage pointer ('Client id from clients_list; empty uses the only client') lives in the schema, not the 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, idempotentHint, and destructiveHint=false, lowering the bar. The description still adds value beyond them: it discloses the 'clients.json' registry source, the 'Never a secret' security guarantee, and the implicit 'default' client behavior when no registry exists.

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 what the tool lists and its fields, followed by the security note and fallback behavior. Slightly dense and run-on in the middle, but 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?

With no output schema, the description carries the burden of explaining the return shape, which it does (client_id, label, sandbox, platforms). It also covers the edge case of no registry, leaving only the sibling-differentiation gap.

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

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

The tool takes zero parameters, so the baseline is 4. The description adds meaningful context about where the data comes from (registry file vs. implicit env-var-derived default) even though there is no parameter syntax to document.

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 (clients this server can work on) and enumerates the returned fields (client_id, label, sandbox, configured platforms), so an agent knows exactly what this yields. It does not differentiate from the sibling client_check or client_profile tools, keeping it just short of 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?

Provides a downstream usage tip ('Pass client_id to the other tools when several clients are listed') and explains the no-registry fallback, which is genuinely useful. However, it gives no explicit when-to-use guidance versus client_check or client_profile, so selection between these sibling tools is left 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?

Beyond the annotations (readOnlyHint, idempotentHint, non-destructive), the description discloses important runtime behavior: per-row current/previous values, change and change_pct with None for zero previous values, totals, metric metadata, resolved date ranges with data_complete, and biggest_moves. It also explains the edge case where a key exists in only one range by showing the other as 0 plus present_in.

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 front-loaded with the core comparison purpose and examples, then moves efficiently into return structure and edge cases. Despite its density, every sentence contributes useful information and there is no redundant restatement of the tool 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?

There is no output schema, so the description carries the burden of explaining return values—and it does so thoroughly: per-row values, change metrics, totals, metric metadata, currency, resolved date ranges, data completeness, and biggest_moves. Combined with a fully documented parameter schema, an agent has everything needed to call and interpret 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?

Schema description coverage is 100%, and the schema already documents every parameter with defaults, enums, and examples. The description adds output semantics tied to parameters (e.g., first metric ranks biggest_moves, date ranges resolved in property timezone), but parameter guidance itself is largely carried by the schema, so the 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?

The description opens with a specific verb and resource: 'Compare a GA4 period with an earlier one in ONE call (Data API runReport with two date ranges)', and immediately distinguishes the tool from ga4_report by directing single-range queries elsewhere.

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 usage examples ('this month against last month, the last 7 days against the 7 before, a month against the same month last year') and explicitly names the alternative tool for the single-range case: 'Use ga4_report for a single range.'

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/idempotent/non-destructive, so the safety profile is covered. The description goes beyond them by disclosing quota behavior (50/25/10 dimensions, 50 metrics) that an agent would not otherwise know, though it does not describe pagination or output shape 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-loads the resource and fields, then adds the quota detail in one compact clause; nothing is redundant. The awkward line break is cosmetic and the 'Read only' clause largely duplicates the annotation.

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 output schema, the description carries the burden of explaining returns and does so by listing the returned fields and quota counts. Adequate for a simple two-parameter read tool; the client/property resolution is left entirely to the schema.

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

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

Schema description coverage is 100% and both parameters (client_id, property_id) are fully documented in the schema, including fallback behavior. The description adds no parameter-level meaning, 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 resource (custom dimensions/metrics of a GA4 property), enumerates the fields returned, and adds quota context. It is clearly a read/list tool, which distinguishes it from the adjacent ga4_plan_custom_dimension_create sibling, 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?

'Read only' signals the mode of use and the quota explanation implies an auditing/inspection scenario, but there is no explicit guidance on when to pick this over ga4_properties or the plan_* creation tools. Usage is only implied.

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 read-only/idempotent safety, and the description adds real value on top: it discloses the two Data API runReport calls (cost/latency signal), the exact output keys including a findings list with severities, and a data_complete flag implying freshness caveats. It stops short of auth or quota details.

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 call mechanics, then return shape, then heuristics — a sensible order. The enumerated output keys are dense but justified because no output schema exists; the phrasing is compact with little 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 output schema, the description carries the return-value burden and does so by naming every top-level key plus the findings structure. Combined with the annotations and a fully documented schema, an agent has enough to call it correctly; only rate-limit/auth expectations are absent.

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%, with date formats, client_id resolution and property_id fallback all documented in the schema. The description adds nothing about parameters — no guidance on date range choice for the audit — 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?

Opening sentence names a specific resource and diagnostic angle: which GA4 events are key events and whether they inflate conversions, with concrete red-flag criteria (more key events than sessions, page_view marked as key, contact clicks marked as key). It is clearly a diagnostic audit rather than a plain listing, which implicitly separates it from ga4_key_events, but 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?

"Run it first on a new property, before reading any conversion rate or ROAS" gives an explicit ordering rule, and the Admin > Events > Key events pointer tells the agent what to do with findings. No explicit exclusions or named alternatives are given, 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered and the description's 'Read only' adds nothing. The only behavioral value added is that key events carry a deletable flag, hinting at mutation routes elsewhere, but there is no word on pagination, scoping, or auth beyond what the schema states.

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 compact sentence, front-loaded with the resource and followed by the field list, then the read-only qualifier. Efficient, though the parenthetical and trailing list make it slightly dense.

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 output schema, the description carries the burden of describing returns, and it does list the returned attributes (event name, counting method, default value, custom/deletable flags). For a simple read-only tool with two optional params this is close to sufficient; only collection-level details like ordering or result shape are 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 both parameters (client_id, property_id) are documented in-schema with defaults and fallback semantics. The description adds no parameter meaning at all, 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?

Names a specific resource (GA4 key events, formerly conversions) and enumerates the fields it surfaces, with 'Read only' distinguishing it from write-oriented siblings such as ga4_plan_key_event_create. It stops short of naming an alternative explicitly, but an agent can tell this is the read counterpart to the create-plan tool.

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 when-to-use guidance, no mention of prerequisites (client_id needed when several clients are registered), and does not route the agent to or away from any sibling. 'Read only' is the only usage signal, and it merely restates the annotation.

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?

Goes well beyond the annotations: it warns that parameterName and scope are immutable, quantifies the quota (50 event / 25 user / 10 item), and discloses that no automatic rollback exists because archiving is not offered. That is exactly the kind of irreversible-consequence context an agent cannot get from readOnlyHint/destructiveHint alone, and it is consistent with readOnlyHint=true since nothing is written.

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?

Four short clauses, front-loaded with the plan-vs-write distinction, then the risk warning, then the apply step. Every sentence carries distinct decision-relevant information with no 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?

For a 7-parameter mutation-planning tool with no output schema, it covers the workflow handoff, irreversibility, and quota limits, and the schema handles client/property selection. It could note how the resulting plan is retrieved (plan_get) or reviewed, but nothing essential 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 schema already labels scope and parameter_name as 'can never be changed later', so the description largely restates parameter facts. Its genuinely additive detail (the 50/25/10 quota) is not per-parameter guidance, so the baseline 3 is right.

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 (plan/register), resource (custom dimension), and target (client's GA4 property), and the 'PLAN (nothing is written)' prefix instantly separates it from apply-style siblings like google_apply and from the read-only ga4_custom_definitions.

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 follow-up action and precondition: 'Apply with google_apply after the user agreed.' That is clear workflow routing, though it stops short of stating when *not* to use this tool or what alternative exists if the user declines.

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 declare readOnlyHint=true/destructiveHint=false, which the description reinforces and enriches: nothing is written, a confirmation_token is returned, user agreement is a prerequisite, and there is no automatic rollback because deletion is not offered in this version. This is behavior beyond what the structured hints 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?

Roughly three dense sentences, front-loaded with the PLAN/nothing-written constraint, then the apply path, then the rollback caveat. 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 mutation-adjacent plan tool with no output schema, the description covers the write-free guarantee, the returned token, the apply handoff, and the missing rollback path. Nothing an agent needs to invoke and follow up correctly is absent.

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 (client_id, event_name, property_id, counting_method) are already documented in the schema with defaults and enum values. The description adds no additional parameter semantics, 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 ('mark an event as a key event of the client's GA4 property') and immediately clarifies the mode with 'PLAN (nothing is written)'. An agent can distinguish it from the sibling apply tools and from ga4_key_events 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?

Explicit two-step workflow: plan here, then 'apply it with google_apply after the user agreed', plus what to do instead if the user wants removal (GA4 Admin > Key events). Names both the next step and the unavailable alternative.

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/idempotent/non-destructive), and the description adds real behavioral context on top: the Admin API must be enabled, no extra OAuth scope is needed, pagination is bounded, and under a client registry only 'owned' properties are queryable.

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 purpose and the return shape, then prerequisites and the registry caveat. Information-dense and mostly waste-free, though the run-on sentence packing return schema, auth, and ownership rules is slightly heavy.

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?

No output schema exists, so the description carries the return-value burden and does so explicitly (properties array fields plus configured_property_id). Combined with precondition and ownership guidance, an agent has everything needed to invoke and interpret 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 coverage is 100%, so the schema already documents client_id and max_pages, setting a baseline of 3. The description adds meaning by tying client_id behavior to the client-registry concept and the 'owned' queryability rule, going beyond the schema text.

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: reading GA4 accounts and properties via the Admin API accountSummaries, so the agent can discover a property_id. It explicitly distinguishes its role from siblings by naming ga4_report and ga4_realtime as downstream consumers of the id 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?

Clear routing: use this to find a property id when you need to pass property_id to ga4_report or ga4_realtime. It also names the ga4_report/ga4_realtime alternatives, though it stops short of stating an explicit 'do not use this when' exclusion.

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, idempotent, non-destructive, openWorld), so the bar is lower, and the description adds the meaningful 30-minute staleness window plus the return shape. With no output schema, disclosing {"rows", "row_count", "totals", "metrics"} is real added value; it stops short of noting latency or sampling behavior for realtime data.

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 plus a compact return-shape sketch; purpose and time window come first. Slightly more than strictly necessary given every input is already documented in the schema, but nothing is padded.

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 4-param tool with full schema coverage and annotations covering safety, this is nearly complete: window, use case and return shape are all present. The one gap is the relationship to ga4_report, which an agent must infer from the word 'realtime'.

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% – metrics, dimensions, client_id and property_id all carry their own guidance, including the client-registry fallback rules. The description adds nothing parameter-specific, 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+resource ('GA4 realtime report') and pins the scope to 'the last 30 minutes', which is enough to separate it from the sibling ga4_report without opening either schema. An agent immediately knows this is the live-window variant.

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 concrete motivating scenario ('check a tracking change, e.g. that one page view is counted once and not twice'), which implies when it is useful. However it never names the alternative (ga4_report for historical ranges) or states when not to use it, so the alternative-selection decision is left 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 the safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is lower, and the description still adds real behavior: results are 'top rows' subject to a limit, totals cover every row regardless, and dates are resolved to the property's timezone with a data_complete flag. That is meaningful operational context beyond the annotations, though permissions/quota behavior is unstated.

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 and scope are front-loaded before the return-value details, and the closing alternative-tool sentence is well placed. The return enumeration is long, but with no output schema it earns most of its words.

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 output schema, the description correctly compensates by describing the return shape (rows, totals, row_count, truncated, metrics metadata, currency, date_range). All parameters are optional and documented in the schema, so an agent has enough to call it; only error/permission behavior 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 all eight parameters are documented there with defaults and accepted formats, so the schema does the heavy lifting. The description only loosely gestures at metrics/dimensions/date range, adding no format or constraint detail beyond what the schema already provides.

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?

It names a specific verb and resource ('Run a Google Analytics 4 report (Data API runReport)') and states the scope ('traffic, conversions or revenue split by any dimensions over a date range'). It also actively disambiguates from the sibling ga4_realtime, so an agent can tell the two apart 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 one explicit routing rule with its selecting condition ('Use ga4_realtime for the last 30 minutes'), which is genuinely useful. It stops short of addressing the other adjacent reporting siblings (ga4_properties, ga4_key_events, gads_query), so there is no full when-not 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 cover readOnly/idempotent/non-destructive, but the description adds real behavioral context: results may come from a 5-minute discovery cache (cached: true), the configured vs. login customer distinction, and hidden_customers counting suppressed accounts. It stops short of auth/rate-limit caveats but goes well beyond the annotation set.

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 purpose and return shape, then layers the client-registry nuance. The second sentence is dense and parenthetical-heavy, but nearly 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?

With no output schema, the description compensates by spelling out the return payload keys (customers[].id, configured_customer_id, login_customer_id, cached). Combined with the client-scoping note, an agent has everything needed to call and interpret this 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 coverage is 100% and the schema already explains that client_id comes from clients_list and empty falls back to the only client. The description adds value by explaining the consequence of client scoping (only the client's own customers are listed), which meaningfully extends the parameter's 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?

States a specific verb+resource: lists Google Ads customer accounts the token can read directly, naming the underlying API call (customers:listAccessibleCustomers). It also positions itself against siblings gads_performance and gads_query as the source of a customer_id for those 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?

Explicitly says to use the result to pick a customer_id for gads_performance or gads_query, and explains the client-registry scoping case. It gives clear context for when this tool is the right one, though it does not state an explicit exclusion or when-not-to-use case.

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 destructive, openWorld, and non-idempotent, so the bar is lower, yet the description adds real operational semantics: locks are re-checked, ops run in order, execution stops at the first error, and everything is journaled. These are exactly the failure-mode and audit details an agent needs before firing a destructive 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 dense sentences, front-loaded with a 'WRITE:' marker that flags the operation class instantly, followed by the required inputs and the execution guarantees. No wasted words.

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 no output schema but rich annotations, the description adequately covers execution behavior and failure semantics for a destructive apply. It could be slightly stronger by noting the journal's recovery/rollback path, but nothing essential for correct invocation 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 schema fully documents plan_id, confirmation_token, and confirm. The description restates the exact-match requirement but adds little beyond the schema and says nothing about the optional client_id, so the 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 (apply) plus resource (a signed Google Ads plan) and immediately flags it as a WRITE operation. The phrase 'after the user approved it' and the reference to the 'plan_* tool' cleanly distinguish it from the sibling plan-creation tools and from rollback_plan.

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 precondition ('after the user approved it') and instructs passing the three values exactly as returned by the plan_* tool. It does not, however, name alternatives such as rollback_plan or plan_list, so an agent must infer the broader workflow.

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, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: a fixed GAQL template on conversion_action via searchStream, name-sorted output, and the REMOVED-filtering rule tied to include_removed.

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 resource, then the returned settings, then the query/filter mechanics. The long field enumeration is dense but informative and each clause carries content; only the multiclause middle sentence strains readability.

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 list tool with full schema coverage and complete annotations, the description covers what is queried, how it is sorted, and what is filtered out. No output schema exists, but the field list effectively pre-describes the return shape, leaving only minor gaps around response volume.

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 are already documented. The description restates the include_removed behavior and name-sorting that the schema also conveys, adding little new parameter-level 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?

States a specific resource (Google Ads conversion actions and their settings) with an explicit enumeration of the fields returned, so an agent knows exactly what it gets back. It never names a sibling such as openai_ads_conversions or ga4_key_events, so differentiation from other conversion-reporting tools relies on the resource name alone rather than explicit contrast.

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 closing sentence gives a concrete use case – 'explain why conversions differ from another platform' – which orients the agent to a real scenario. It offers no exclusions, prerequisites, or named alternatives, so a 5 is not warranted.

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?

Goes well beyond the readOnly/idempotent/openWorld annotations: it discloses the fixed-template query model, highest-spend-first ordering, totals semantics (ROAS = sum of values / sum of spends), the totals_complete caveat that totals cover up to 10,000 rows, the invalid_dates error case, currency lookup when no row is present, and the account-timezone date_range with data_complete. That is unusually rich behavioral 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?

Front-loaded with the core purpose and metric list, then packs return-shape details into a dense second half. Every sentence carries information, though the long comma-spliced tail listing returned fields is harder to scan than the opening.

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 output schema, the description carries full responsibility for explaining returns, and it does: rows, totals, totals_complete, currency, date_range, data_complete, metric units/definitions and attribution. An agent can call this correctly and interpret the output without further documentation.

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 earns a bump by surfacing the hidden requirement that start_date/end_date must be non-empty (they are schema-optional with default ''), the invalid_dates failure mode, and the currency/customer_id fallback behavior. It also documents the shape of the returned rows and totals that the parameters drive.

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 — 'Google Ads performance by account, campaign or ad group over a date range' — plus the exact metric set and segmentation options. It also implies differentiation from gads_query by noting results come from 'fixed aggregated GAQL templates (searchStream),' 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?

Usage is implied by the metric/level/date-range framing, and it flags that start_date and end_date are required (empty -> invalid_dates). But it offers no explicit when-to-use vs when-to-use-something-else guidance, and never routes the agent to gads_query for arbitrary GAQL or to gads_accounts for account discovery beyond a parenthetical.

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?

Adds real operational context beyond annotations: the request is atomic, Google dry-runs it first, negatives can only suppress delivery (no spend risk), and rollback is manual. Annotations already cover read-only/non-destructive status, so the remaining gap (what the plan artifact looks like, how it is later applied) is minor.

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 tight sentences with the action and targets front-loaded; the parenthetical restating the 1-50 limit and match types duplicates the schema slightly but is compact. No filler or hedging.

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?

Covers target selection, limits, atomicity, the dry-run behavior, risk profile, and rollback for a six-parameter mutation-planning tool with no output schema. It does not describe the plan output/next step, which is the only notable omission.

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 schema already documents keywords, match_type, client_id, customer_id, campaign_id, and shared_set_id. The description echoes the keyword count, match types, and target selector but adds only the campaign-vs-shared-set exclusivity nuance, which the schema also hints at.

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 (add), resource (negative keywords), and scope (to a campaign or a shared negative keyword list) in one atomic request. It is immediately distinguishable from siblings such as gads_plan_pause_entities or gads_plan_create_campaign 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?

Clearly explains the two targeting modes (campaign_id or shared_set_id) and signals that this is a Google-side dry-run plan whose rollback is manual removal in the interface. It stops short of naming the execution step (applying the plan, e.g. via gads_apply) or quantifying when to prefer this over other gads_plan_* 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description does not contradict them — it plans rather than mutates. Beyond that it discloses what happens at call time: the current budget and currency are read first, the policy caps the value (max_daily_budget_micros in cap_currency, +20% per 24h), a human approval is required downstream, and a shared budget affects every campaign using it.

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?

Four dense sentences, front-loaded with the amount/semantics and target selection, then policy and approval behavior. Little waste, though the micros conversion example duplicates what the schema already states.

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 planning tool with no output schema, it covers target selection, unit semantics, policy caps, approval flow, and shared-budget side effects. It stops short of telling the agent how to inspect the resulting plan (plan_get/plan_list) or whether the plan expires, which would complete the loop.

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: it explains the micros unit against the account currency with a worked example, and clarifies the either/or relationship between budget_id and campaign_id that the schema presents only as two loosely described fields. The currency/micros example partially repeats the schema, keeping it out of 5 territory.

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: 'Plan a new daily amount for one Google Ads campaign budget'. It also explicitly distinguishes itself from the apply step ('a human approval is required before gads_apply'), so an agent can tell this planning tool apart from its sibling execution 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?

Gives concrete targeting guidance ('Give budget_id, or campaign_id to change the budget that campaign uses') and names the follow-up alternative gads_apply along with the approval gate that separates planning from execution. The conditions for use are explicit rather than inferred.

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 description adds real context beyond the annotations: the request is a Google-side dry-run, nothing downstream (ad groups, keywords, ads) is created, the bidding strategy is hard-fixed to manual CPC with no bid amount, and the campaign remains PAUSED until activated in the Google Ads UI. This is consistent with readOnlyHint=true and destructiveHint=false, though it does not address the declared idempotentHint=false (e.g. whether re-planning the same name yields a new plan).

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 key constraints are front-loaded, and each sentence carries distinct information (budget ownership, network, atomicity, bid strategy, paused state, approval gate). It is dense and slightly fragmented by line breaks, but there is 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?

There is no output schema, yet the description covers everything needed to call this correctly: what gets created, what explicitly does not, the fixed bidding strategy, the budget semantics, the paused lifecycle and the approval/apply follow-up. Nothing material is left ambiguous for a four-parameter planning 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 coverage is 100%, so the schema already documents name, client_id, customer_id and the micros budget. The description still adds meaning by clarifying the budget is the campaign's own and not shared, plus the account-currency micros convention, which is the one parameter most easily mis-scaled by an agent.

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 ('Plan creating one Google Ads Search campaign') and pins down scope precisely: PAUSED, own non-shared daily budget, Search network only, single atomic request. It also states explicitly what is NOT produced (no ad group, keyword or ad), which lets an agent distinguish this from sibling planning tools such as gads_plan_budget_change or gads_plan_add_negatives.

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 places the tool in a workflow by noting the plan stays paused and requires human approval before gads_apply, so the agent understands this is the planning step and gads_apply is the execution step. It does not explicitly say when to choose this over a sibling campaign-planning tool or what preconditions (e.g. an existing client/customer id) are required, so it falls short of full alternative 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?

Despite readOnlyHint/destructiveHint annotations already covering the safety profile, the description adds substantial context: each entity is read first (status kept for rollback), it is dry-run via validateOnly, the pause stops spending, and rollback re-enables only under a condition. This is well 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-loads the purpose and packs the key mechanics (read-first, dry-run, ad-id format, follow-up, rollback caveat) into a tight block. Dense but every clause earns its place; minor crowding from the rollback/spend sentences keeps it from a 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?

No output schema exists, yet the description explains what the plan returns (diff, risks, confirmation_token, confirm) and the required user-facing flow, plus the ad-id syntax. An agent has everything needed to call it and hand the result back.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including the '<ad_group_id>~<ad_id>' ad-id format. The description restates the same ad-id format rather than adding new semantics, 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+resource: 'Plan pausing Google Ads campaigns, ad groups or ads (status PAUSED, nothing else).' The explicit scope 'nothing else' and the entity list distinguish it from siblings like gads_plan_budget_change and gads_plan_add_negatives without needing to open 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 a clear workflow: show the returned plan to the user, then call gads_apply, and notes that rollback_plan re-enables only if allow_activate is set. It names the follow-up tools but stops short of an explicit when-not-to-use statement or contrast against other plan_* 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?

Goes far beyond the readOnly/idempotent annotations: it discloses that malformed queries are refused with no network call, the exact validation rules (single SELECT, no ';', '--', '/*' even in literals, ASCII only, no backslash/JOIN), the server-side row bounds (LIMIT 10001 injected or lowered, 20 MB cap), the resource allowlist and the sensitive_resource refusal list, the env-var override, and the returned row shape. This is unusually complete behavioral disclosure for a mutation-free 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?

Front-loaded correctly: purpose and the gads_performance differentiator come first, then the validation and bounds. It is long but nearly every clause carries a constraint the agent must satisfy; only the resource allowlist is bloated by enumeration and the no-';' rule duplicates the schema text.

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 raw-query tool with no output schema this covers the full contract: input grammar, refusal behavior, row/byte caps, allowlisted resources, sensitive-data refusals, and the return shape (flattened GAQL field names, *_micros → currency units). Nothing an agent needs to formulate a valid, non-refused query 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 gaql, limit, client_id and customer_id are already documented; the description mostly restates the gaql constraint that the schema states verbatim. It adds some value by explaining the interaction between a user LIMIT and the internal 10,001 ceiling, but says nothing extra about client_id/customer_id resolution or the output `limit` semantics.

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 (run a read-only GAQL SELECT), the resource (one Google Ads customer via searchStream), and the scope that distinguishes it from siblings ('fields the fixed gads_performance templates do not cover'). An agent can separate this from gads_performance, gads_accounts and gads_conversion_actions 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 phrase 'for fields the fixed gads_performance templates do not cover' explicitly routes the agent away from the sibling and toward this tool when the templated report is insufficient. It also states the prerequisite (a customer_id from gads_accounts / GADS_CUSTOMER_ID), though it never gives explicit when-not-to-use exclusions for the other gads 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 flag destructive/openWorld/non-idempotent, yet the description adds execution semantics beyond them: locks are re-checked, ops run in order, execution halts on first error, and everything is journaled. It also imposes a token-integrity constraint (pass values exactly as returned), which is real behavioral guidance not present in the structured fields.

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 'WRITE:' marker followed by two dense sentences; every clause earns its place by covering scope, precondition, parameter integrity, and execution/failure semantics 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?

For a destructive, non-idempotent mutation tool with no output schema, the description covers the critical facts (approval gate, exact token passing, lock re-check, ordered execution, stop-on-error, journaling). It could go further by noting how to verify the result (audit_log) or undo it (rollback_plan), which keeps it from a 5.

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 a meaningful constraint beyond the schema: plan_id, confirmation_token and confirm must be passed 'exactly as the plan_* tool returned them,' which conveys a provenance/integrity requirement the field descriptions do not state.

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 and object ('WRITE: apply a signed plan') and enumerates the exact platforms it covers (GA4, Search Console, Merchant, GTM), which distinguishes it from the sibling apply tools (gads_apply, meta_apply, openai_ads_apply). An agent can route to it 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?

States a clear precondition ('after the user approved it') and implies the plan_* -> apply workflow by requiring the exact values the plan_* tool returned. It does not name when NOT to use it nor point to rollback_plan/audit_log as follow-ups, so it stops short of explicit alternatives.

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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description usefully adds a hard operational constraint the annotations cannot express: a quota of 2,000 inspections per day. It does not, however, explain quota accounting or auth prerequisites beyond what the schema implies.

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: purpose first, then the quota constraint. Nothing is padded and every clause 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 no output schema present, the description compensates by enumerating the returned fields, and it flags the daily quota. Combined with 100% schema coverage of inputs and full annotation coverage of the safety profile, an agent has everything needed to call this 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%, so the two optional parameters (site_url, client_id) and the required url are already fully documented in the schema. The description adds no additional parameter-level semantics, 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 action and resource: 'Google index status of one URL (URL Inspection API)', scoping it to a single URL. It then enumerates exactly what the result contains (verdict, coverage state, canonicals, robots.txt state, page fetch state, last crawl time), which makes it unmistakable against data-oriented siblings like gsc_performance or gsc_sitemaps.

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 explicit when-to-use or when-not-to-use guidance, and no sibling is named as an alternative. Usage is only implied by the scope phrase 'one URL', which a capable agent can infer but which is not spelled out.

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, idempotent, open-world and non-destructive behavior, so the description's 'Read only' line is redundant. However, it adds a meaningful behavioral rule beyond annotations: a key absent from one period is counted as a full loss or full gain, which materially affects interpretation.

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 front-loaded and efficient: it names the report first, then explains comparison periods and output fields. The only minor waste is 'Read only', which repeats an annotation.

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?

There is no output schema, and the description does a good job explaining returned fields: clicks, impressions, CTR, position for both periods, totals, and both date ranges. It also covers the key behavioral quirk for missing keys, making the definition complete enough to invoke and interpret 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%, so all five parameters are already documented, including the date windows, limit, site/client context and dimension enum. The description reinforces the N-days-against-N-days comparison but adds little parameter meaning 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 clearly states a specific verb and resource: it returns Search Console week-over-week movers in queries or pages, with loss/gain framing. It does not explicitly differentiate itself from nearby GSC siblings such as gsc_performance or gsc_opportunities, so it falls short of 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?

The intended use is strongly implied by 'week-over-week moves' and 'lost and gained the most clicks', but there is no explicit when-to-use guidance and no named alternatives. An agent can infer this is for mover analysis rather than general performance reporting, but must still decide among GSC tools itself.

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, idempotentHint and destructiveHint=false, so safety is covered; the trailing 'Read only' is largely redundant. The description does add real behavioral context the annotations cannot: a single request, a window of the last N days ending two days ago (a data-freshness lag), and that each list is sorted by impressions. Return-field detail is absent but there is no output schema to lean on, so a 4 rather than 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 resource and its two result lists, followed by two short supporting sentences on time window and read-only nature. The first sentence is dense and run-on, and 'Read only' is wasted given the annotations, but nothing is padded.

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, no-output-schema tool the description does the necessary work: it defines both result lists, the sort order, and the data window. What is missing is the per-row shape (which metrics accompany each query/page) and whether the no_clicks list is also bounded by limit, though the schema's 'rows returned in each list' largely covers the latter.

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 3. The description does add one genuinely non-schema fact — that min_position, max_position and min_impressions scope only the striking_distance list, not no_clicks — but it leaves days/limit/dimension/client_id entirely to the schema, so it does not exceed the baseline by much.

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-plus-resource framing and, more importantly, spells out the exact two output lists it produces ('striking_distance' filtered by position and impressions, 'no_clicks' for zero-click rows). That makes it clearly distinguishable from gsc_performance or gsc_inspect_url without opening a schema. It stops short of naming those siblings explicitly, 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 only implied: the phrase 'opportunities' and the striking-distance/no-clicks definitions suggest an optimization-audit scenario, but the description never states when to pick this over gsc_performance or gsc_inspect_url. There are no exclusions or preconditions beyond the client/site resolution already carried by the schema.

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/idempotent/openWorld, so the bar is lower, and the description goes well beyond them: it discloses that results are the top rows only, that a 'truncated' flag exists, that 'totals' cover the whole period with the same filter but no split, and that dates are reported in Pacific Time with a 'data_complete' field. It does not mention auth requirements or rate limits, but the return-shape transparency is substantive.

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 dense sentence, front-loaded with what is measured, then the split options, then the return structure. Every clause (totals semantics, truncation, metric definitions, timezone) carries information; only minor tightening is possible.

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 output schema, the description has to explain the return payload, and it does so for the key fields (totals, truncated, metrics, date_range/data_complete). Combined with 100% schema coverage on the eight input parameters, an agent has enough to call and interpret this tool, though routing guidance and pagination nuance are thin.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters including defaults, enum values, and the data-lag behavior. The description adds no syntax or constraint detail beyond what the schema provides, 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?

The description names a specific verb+resource (Google Search Console search performance for the configured property) and enumerates the metrics and split dimensions returned. An agent can distinguish it from gsc_inspect_url, gsc_sites, or gsc_sitemaps 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?

Usage is implied by the metric-and-dimension framing (pull aggregated GSC performance data), but there is no explicit when-to-use versus alternatives such as ga4_report or gads_performance, and no statement of prerequisites or exclusions. Adequate for an agent that already knows it wants GSC data, but it does not route.

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, and the description adds real context beyond them: nothing is written at plan stage, the 'Low risk' assessment, the domain/prefix scoping constraint, and the precise rollback semantics including the permission and approval requirements. No contradiction with the read-only annotation since planning performs no write.

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 key fact ('PLAN (nothing is written)'), followed by constraint, risk level, apply path, and rollback conditions. Every sentence carries distinct, 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?

For a plan-only tool with no output schema, the description covers the full lifecycle an agent needs: what planning means, the input constraint, the risk level, how to apply, and the rollback options and their requirements. Nothing essential to correct invocation 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, but the description adds genuine meaning for sitemap_url by defining the placement constraint (same domain or subdomain for sc-domain:, same prefix for URL-prefix properties). It does not elaborate on site_url/client_id beyond what the schema already states.

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 ('submit a sitemap to the client's Search Console property') and immediately flags the plan-only nature ('PLAN (nothing is written)'). An agent can tell this apart from the sibling gsc_sitemaps (list) and from apply tools without opening schemas.

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 the agent: 'Apply with google_apply after the user agreed,' and explains the rollback path in detail, including prerequisites (write.gsc.allow_delete and human approval) and the case with no rollback. When-to-use and the alternative follow-up tools are all named.

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, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value by disclosing the returned fields (submission/download timestamps, errors, warnings), which matters since there is no output schema, but it says nothing about auth requirements beyond the schema, rate limits, or whether sitemap data can be stale.

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 most important content (what sitemaps and which fields) comes first. It is efficient, though the noun-phrase form leaves the action verb implicit.

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 read tool with full schema coverage, annotations, and no output schema, the definition is adequate: it tells the agent what data comes back. It stops short of explaining scope (single property at a time), result limits, or how it relates to the sibling sitemap-submission 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 both site_url and client_id are fully documented in the schema, including the fallback behavior and client-registry constraint. The description adds no parameter-level meaning beyond that, 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 the specific resource (sitemaps declared in Search Console) and enumerates the data surfaced: last submission, last download, errors, warnings. The retrieval verb is only implied ('Sitemaps declared in...'), and it doesn't explicitly distinguish itself from siblings like gsc_sites or gsc_plan_sitemap_submit, but an agent can tell this is the sitemap-status read.

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?

No when-to-use guidance, no prerequisites, and no alternatives named. It never says to use gsc_plan_sitemap_submit for submitting a sitemap or gsc_sites for property listing, so routing between the GSC read tools is left entirely 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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description's 'Read only' adds nothing. What it does add is genuinely non-obvious behavior: with several clients registered, other clients' sites are masked, and the returned permission level determines whether sitemaps may be submitted.

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 dense sentence that front-loads the resource before listing returned attributes. The parenthetical enumerations of address format and permission levels are useful but make it slightly run-on.

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 output schema, the description usefully enumerates what is returned (address, permission level, whether it is the configured site, whether sitemaps may be submitted) and discloses the multi-client masking caveat. Nothing essential to invoking a single-optional-parameter read tool appears to be 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 client_id is already documented in the schema (including 'Required when several clients are registered'). The description nevertheless adds meaning to that parameter by explaining the multi-client masking consequence that makes client scoping matter.

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 resource and scope: the Search Console properties visible to the client's Google token, with the address format (sc-domain: or URL prefix) spelled out. It is clearly distinct from gsc_performance, gsc_sitemaps and gsc_inspect_url by resource, though it never names those siblings to route the agent 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 explicit when-to-use or when-not-to-use guidance, and no alternatives are named. Usage is only implied: a discovery step for properties before calling gsc_performance or gsc_sitemaps. The multi-client masking note hints at the scoping condition but is not framed as usage advice.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description goes beyond them by disclosing the returned contents and, critically, the fingerprint dependency on gtm_plan_tag_upsert, which is behavioral context the annotations cannot express.

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, front-loaded with the resource and scope before the downstream dependency. It is efficient with no filler, though the parenthetical field list and wrapped line slightly impede scannability.

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 output schema, the description carries the return-value burden and does so by naming the fields returned. The read-only annotations cover safety, and the upsert linkage covers intent; only edge cases (tag not found, error behavior) are unaddressed, 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 tag_id, client_id, and workspace_id are already documented in the schema (including the multi-client requirement and the Default Workspace caveat). The description adds no parameter-level meaning, which is the expected baseline when the schema does the heavy lifting.

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 (one tag of a workspace), then enumerates the returned surface (type, parameters, triggers, paused, fingerprint). An agent can distinguish it from gtm_get_trigger and gtm_get_variable purely from the text, since the resource noun is explicit and the sibling names share the same suffix pattern.

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 implicitly routes the agent: this is the read step whose fingerprint is required by gtm_plan_tag_upsert to perform an update, so it signals when to call it in the workflow. It does not, however, state when not to use it or mention alternative reads such as gtm_versions or gtm_workspace_status.

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, idempotentHint, openWorldHint and destructiveHint=false, so 'Read only' restates structured data. The one piece of added value is that the returned fingerprint is required for updates, which explains why an agent would call this before a write.

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 compact sentence with the resource and scope front-loaded and no filler. The stacked parentheticals make it slightly dense but nothing is 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?

No output schema exists, and the description does state the shape of the return (type, filters, fingerprint), which is the key missing piece. Combined with 100% schema coverage and annotations carrying the safety profile, it is nearly complete, though error/permission behavior is unstated.

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 all three parameters (client_id, trigger_id, workspace_id) are documented in the schema, including the multi-client fallback and the Default Workspace caveat. The description adds no parameter-level 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?

Names a specific verb (get) and resource (one trigger of a workspace) and even scopes the payload (type, filters, fingerprint). An agent can separate it from gtm_get_tag and gtm_get_variable by resource, though no sibling is named 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 parenthetical 'needed to update it' implies the fetch-then-upsert flow (presumably feeding gtm_plan_trigger_upsert), which is useful context, but there is no explicit when-to-use, when-not-to-use, or named alternative.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral value by disclosing that the returned fingerprint is the prerequisite for updating the variable, which tells an agent why to call it and what to do with the result.

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 tight sentence that front-loads the resource and scope, followed by the fingerprint rationale and a read-only qualifier. No filler, though the trailing 'Read only' is slightly redundant against the 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?

For a 3-parameter read tool with no output schema, the description adequately conveys what comes back (full variable with type, parameters, fingerprint) and the schema fully documents the inputs. Nothing essential to correct invocation 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%, with client_id, variable_id, and workspace_id all documented in the schema itself (including the 'never the Default Workspace' caveat). The description adds no parameter-level detail beyond what the schema already provides, 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+resource: fetches one GTM variable of a workspace in full, and names the content (type, parameters, fingerprint). The word 'variable' implicitly separates it from the sibling getters gtm_get_tag and gtm_get_trigger, though neither is named 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 parenthetical 'needed to update it' implies the intended workflow (read the fingerprint before an update), and 'Read only' clarifies the operation class, but there is no explicit statement of when to choose this over gtm_inventory or gtm_workspace_status.

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, idempotent, non-destructive, openWorld), so the description's job is to add context — and it does: it discloses that only the default workspace is covered, that the live published version id is included, and that built-in trigger ids are humanized. It does not disclose result size or pagination behavior, which keeps this below 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 returned contents, then qualifications, then the use case — a sensible ordering. Dense but every clause carries information; only the trailing 'Useful to spot...' sentence is mildly promotional rather than factual.

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 output schema, the description must describe the return payload, and it does enumerate the fields returned (tags with type/paused/firing triggers/parameters, triggers, variables, live version id) along with the container/workspace scope. It omits how the single client_id parameter affects behaviour and any size/rate caveats, so it is good but not fully complete.

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 there is a single optional client_id fully documented in the schema, so the baseline is 3. The description never references client selection at all, adding no meaning beyond the schema's 'Client id from clients_list' explanation.

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 the resource and its scope precisely: tags (with type, paused, firing triggers, parameters), triggers, variables of the default workspace, plus the live version id. It is implicitly distinguished from the single-entity getters (gtm_get_tag, gtm_get_trigger, gtm_get_variable) by being a whole-container inventory, but no sibling is named and there is no explicit verb.

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 final clause ('Useful to spot a tag configured twice') gives one concrete use case, which is better than nothing, but there is no statement of when to prefer this over gtm_get_tag/gtm_get_trigger/gtm_get_variable for a single entity, nor any prerequisite or exclusion.

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?

Goes well beyond annotations: it clarifies why readOnlyHint=true holds despite needing a write token ('no version is created, nothing goes live') and discloses the exact auth prerequisites (scope tagmanager.edit.containerversions, writes enabled for the client). That reconciles an otherwise confusing safety/scope pairing and is exactly the kind of context annotations cannot 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?

Front-loaded with the action and outcome, then behavior guarantees, then auth requirements. Three dense sentences with little waste; 'so there is nothing to apply' mildly restates 'it changes nothing', which keeps it below 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?

With no output schema, the description still specifies what gets reported (compiler errors, merge conflicts, workspace contents), confirms nothing persists, and covers auth scope. Nothing an agent needs to invoke 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 both parameters (client_id, workspace_id) are already fully documented in the schema, including the 'never the Default Workspace' constraint. The description only refers to 'a workspace' and 'the client' generically and adds no syntax or format detail, 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 ('compile a workspace into a throw-away preview version') and names the outputs ('compiler errors, merge conflicts and what it holds'). An agent can distinguish this from siblings like gtm_plan_workspace_create or gtm_workspace_status 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?

Frames the tool as the 'Preview step of a GTM plan' and rules out any follow-up ('there is nothing to apply'), which tells the agent when in a workflow to call it. It does not explicitly name alternative siblings (e.g. gtm_workspace_status) or exclusions, so it stops short of the top score.

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 partly covered. The description strengthens this with 'nothing is written', 'nothing goes live: publishing stays in the GTM interface', the Custom HTML risk warning, and the rollback path — all meaningful context 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?

Front-loaded with 'PLAN (nothing is written)', then scope, then workflow. Every clause (fingerprint, no-publish, Custom HTML risk, apply/rollback) 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?

For a nested-object, mutation-style planning tool with no output schema, the description covers the plan/apply lifecycle, risk, and reversibility well. It lacks detail on the plan artifact itself (e.g., what plan_get returns or plan_id handling), and client_id selection is left entirely to the schema.

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

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

Schema description coverage is 100%, so the schema already documents the workspace constraint, the fingerprint-staleness rule, client_id selection, and the partial-update semantics. The description's mention of the fingerprint duplicates that structured data, 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 (create or update = upsert) and resource (GTM tag in a non-default workspace), explicitly marked as a plan-only operation. An agent can distinguish this from gtm_plan_trigger_upsert, gtm_plan_variable_upsert, and gtm_get_tag 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?

Routes the agent explicitly: names gtm_get_tag as the source for an update fingerprint, google_apply as the apply step after user agreement, and rollback_plan as the undo path. Conditions for using the tool vs. its alternatives are stated, not inferred.

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, and the description reinforces this with 'nothing is written' rather than contradicting it. It adds genuinely useful context beyond the annotations: the plan-then-apply handoff via google_apply and the fingerprint dependency (from gtm_get_trigger) for updates. It does not describe the plan artifact returned or its lifetime, which keeps it from 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?

Two sentences, front-loaded with the critical 'PLAN (nothing is written)' signal, followed by the operation and the apply handoff. No filler; every clause 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?

For a plan-only tool with no output schema, the description covers the essentials: the no-write guarantee, the workspace constraint, the update fingerprint path, and the apply step. It omits how the resulting plan is retrieved or reused (e.g., via plan_get), which is a minor gap against the plan_* sibling ecosystem.

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 every parameter (trigger, client_id, trigger_id, fingerprint, workspace_id) is already documented in the schema, including the update-only fingerprint requirement. The description only echoes the fingerprint-for-update point, adding no syntax or format detail 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 (plan/create-or-update) and resource (GTM trigger) with a scope qualifier ('non-default workspace of the client's GTM container'), and the PLAN/nothing-is-written framing immediately separates it from the sibling gtm_plan_tag_upsert and gtm_plan_variable_upsert. An agent can identify exactly what this tool does 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 workflow: use this to stage the change, then 'Apply with google_apply after the user agreed.' This tells the agent when to invoke it and what the follow-up is. It stops short of explicit when-not conditions or naming alternative plan tools, but the resource type plus the plan/apply pattern 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 declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'nothing is written'. It adds genuine context beyond the annotations: the fingerprint source, the 'Custom JavaScript variables are high risk' warning, and the required apply-after-consent workflow.

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 critical 'PLAN (nothing is written)' scoping, then update mechanics, then the apply step. No wasted words.

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 output schema, the description still conveys the plan-then-apply workflow and the fingerprint/workspace prerequisites, which is enough for an agent to call it correctly. It does not mention what the resulting plan is or how plan_get/plan_list/rollback_plan relate, a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters, including the variable object shape and fingerprint staleness rule. The description reinforces the fingerprint source and non-default workspace constraint but adds little beyond what the schema already states.

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 action (PLAN, nothing written) plus the resource (a GTM variable) and the scope constraint (non-default workspace of the client's GTM container). It cleanly distinguishes itself from gtm_get_variable and from the tag/trigger upsert siblings by naming the resource.

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?

Points to gtm_get_variable as the source of the fingerprint for updates and names google_apply as the follow-up with the condition 'after the user agreed', which is clear context. It stops short of explicit when-not-to-use exclusions against siblings like gtm_plan_tag_upsert.

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, and the description reinforces this with "nothing is written" and "Low risk: a workspace changes nothing live." It adds the important non-obvious caveat "No automatic rollback," though it doesn't address the non-idempotent hint (repeated-call behavior).

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?

Information is front-loaded and every clause carries weight (plan semantics, write scope, risk, apply path, rollback caveat). It's slightly run-on with stacked parentheticals, which costs a point but no sentence is 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?

For a 3-parameter planning tool with full schema coverage and clear annotations, nothing an agent needs to call it correctly is missing. The plan/apply boundary and the absence of output-schema expectations are handled adequately.

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

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

Schema description coverage is 100%, so the schema already documents name, client_id, and description with useful detail (uniqueness, when client_id is required). The description adds no parameter-level syntax 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?

States a specific verb and resource ("create a dedicated workspace in the client's GTM container") and immediately clarifies the planning semantics, so an agent can distinguish it from the gtm_plan_tag/trigger/variable_upsert siblings. The parenthetical "PLAN (nothing is written)" front-loads what the tool actually does.

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: plan here first, then "Apply with google_apply after the user agreed," naming the concrete alternative. It also states the boundary that the Default Workspace is never written, leaving nothing 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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that: the sort order (newest first), what each row contains, that the live version is marked, and an explicit statement that publishing is unavailable.

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 tight sentences with no filler; the scope ('Read only: publishing is not offered') is stated up front rather than buried, and the returned-field parenthetical is compact.

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 output schema, the description usefully enumerates the returned fields, and annotations carry the safety profile. For a two-parameter read tool this is close to complete, though it could say more about pagination/limit behavior and when this beats gtm_workspace_status.

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 parameters (limit, client_id) are already documented in the schema, including the multi-client requirement. The description's 'the client's GTM container' only loosely corroborates client_id and adds nothing about the limit.

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 the resource (client's GTM container versions), the ordering (newest first), the fields returned (id, name, tag/trigger/variable counts), and that the live version is flagged. It is clearly distinguishable from get-style siblings like gtm_get_tag, though it never uses an explicit verb such as 'list' and does not name a sibling alternative.

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 infers it should call this to inspect version history or find the live version. The 'publishing is not offered' line sets a scope boundary but does not route the agent to an alternative tool (e.g. a plan/publish sibling), and no when-not conditions are given.

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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds value beyond them by disclosing the exact return shape (workspaces, pending added/updated/deleted tags, triggers, variables, merge conflicts) and the constraint to use a non-default workspace for changes.

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 resource being read, and the read-only caveat is placed last where it reads as a constraint. The first sentence is dense but every element earns its place by describing return content.

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?

There is no output schema, but the description compensates by enumerating the returned fields in detail, and the annotations cover the safety profile. For a two-parameter read tool this is close to complete; only the maximum-workspace count and pagination nuance are left to the schema.

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

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

Schema description coverage is 100%, with client_id and workspace_id both documented (including 'empty uses the only client' and 'empty lists every workspace'). The description adds no parameter-level detail beyond what the schema already provides, so the 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: it returns the workspaces of the client's GTM container, enumerating the exact fields (id, name, default flag, server-created flag) plus pending changes and merge conflicts. An agent can distinguish it from siblings like gtm_inventory or gtm_versions 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?

The closing clause 'Read only; use a non-default workspace for any change' gives clear read-versus-write context and a default-workspace caveat. It stops short of naming an explicit alternative tool (e.g. gtm_plan_workspace_create), so it is strong context rather than 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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: which notification categories are returned and the fact that absent notifications are reported as such rather than erroring.

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, all front-loaded with the core deliverable first. The 'Read only: nothing is submitted' clause is slightly redundant against readOnlyHint but is brief and reinforces rather than clutters.

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 2-parameter read tool with full schema coverage and complete annotations, this covers what an agent needs, including the empty-result behavior. Only the shape of the returned notification data is left unspecified, which is minor given there is no output schema to describe anyway.

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% — both 'url' and 'client_id' are documented in the schema, including the multi-client condition for client_id. The description adds no parameter-level 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?

The description names a specific resource and scope: 'Latest Indexing API notifications (URL_UPDATED / URL_DELETED) Google holds for a URL.' The enumeration of the two notification types makes it unambiguous and distinguishable from sibling lookups like gsc_inspect_url or gsc_sitemaps.

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 resource description, and the note that 'most URLs were never notified' usefully sets expectations. However, it never states when to prefer this over gsc_inspect_url or gsc_sitemaps, nor any prerequisites for having Indexing API data available.

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=true and destructive=false, so 'Read only' is redundant. The description nonetheless adds real behavioral context by disclosing the return shape (title, severity, detail, documentation link, impacted destinations per country) and the severity taxonomy (CRITICAL, ERROR, SUGGESTION), which matters because no output schema exists. It omits pagination, auth, or rate-limit behavior.

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 resource and scoped to one dense sentence plus a short safety tag; every clause carries information. The field enumeration is slightly list-heavy but earns its place given the missing 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, 3-optional-parameter diagnostic tool with no output schema, the description covers the resource, the issue domain, and the returned fields well enough to call it correctly. What is missing is only routing guidance toward merchant_product_issues.

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 client_id, account_id, and language_code are fully documented in the schema (including the multi-client requirement and BCP-47 language format). The description adds nothing about parameters, 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 resource (account-level issues of the client's Merchant Center account) with concrete scope and enumerates the issue categories (suspensions, policy, shipping, tax, website claim). The 'Account-level' wording cleanly separates it from the sibling merchant_product_issues, so the agent can distinguish them 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?

Implicit usage is clear from the description (diagnose account-level Merchant Center problems), but there is no explicit when-to-use statement, no exclusions, and no routing to the obvious alternative merchant_product_issues. Usage is inferable but left to the agent.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the practical detail that results include labels, countries, languages, and fetch URLs, which tells the agent what the feed records contain, but it says nothing about scoping, pagination, or per-account behavior.

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 the resource and returned fields front-loaded and zero filler. It is slightly clipped as a verbless fragment, which costs a little clarity but nothing is 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 simple read-only tool with one optional parameter, full schema coverage, and annotations carrying the safety profile, the description supplies the one thing structured data does not: the fields a data source record exposes. Missing only secondary detail like result scoping or pagination.

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 client_id parameter is fully documented in the schema, including the condition for when it is required. The description adds no parameter-level 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?

The description names a specific resource, Merchant Center data sources, and disambiguates with the parenthetical alias '(feeds)', which separates it from siblings like merchant_products and merchant_account_issues. However, it never states the operation (list/get), so the agent must infer that this is a read/list call from the noun phrase 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?

There is no when-to-use guidance, no mention of alternatives, and no note about prerequisites such as when a merchant account must be configured first. The agent gets a resource name and a field list but nothing that routes it between this tool and the other merchant_* 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 only declare safety hints; the description adds rich behavior beyond them: risk tiers per attribute (title/description low, link/availability medium, price high), human approval requirement for price, budget caps (write.merchant.max_daily_budget_micros, max_increase_pct, cap_currency), the ~30-minute propagation delay, and rollback via rollback_plan. Nothing is written — consistent with readOnlyHint=true.

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?

Every clause carries information (risk tiers, caps, timing, exclusions) with the plan-only constraint front-loaded in capitals. It is dense and somewhat run-on, but no sentence is 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?

For a mutating-adjacent planning tool with no output schema, the description covers the write path, approval gates, budget caps, latency, rollback, and explicit non-capabilities. An agent has everything needed to plan and then hand off to google_apply.

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 3, but the description adds a genuine semantic rule for update_mask: 'an attribute listed without a value is refused: Google would delete it.' That constraint is not derivable from the schema and prevents a destructive mistake.

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 ('PLAN (nothing is written): change some attributes of one product of the client's Merchant Center account') and distinguishes itself from siblings like merchant_products by emphasizing the plan-only nature. An agent can tell exactly what this does 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 routes to the apply step ('Apply with google_apply after the user agreed') and states exclusions ('Product insert, delete and inventories are deliberately not offered'). This is the when/when-not/alternatives pattern at full strength.

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, idempotentHint, openWorldHint and non-destructive, so the bar is lower. The description still adds real behavioral context: it scans every page of products up to max_pages, so unbounded-ish work is disclosed, and it explains the truncation semantics via the returned 'truncated' 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?

Two dense sentences with the purpose front-loaded and the return shape compactly inlined as a literal JSON sketch. No filler or hedging; only minor cost is the somewhat cramped embedded schema notation.

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?

No output schema exists, so the description carries return-value burden and does so by enumerating the product and issue fields (offer_id, feed_label, title, link, code, severity, attribute, destination) plus scanned/truncated. Combined with annotations covering the safety profile, this is nearly complete; only the routing against account-level and patch siblings 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 schema already documents limit, max_pages, only_with_issues and client_id thoroughly. The description only echoes max_pages scoping and the return shape; it adds no format or interaction detail (e.g. how limit interacts with the 'scanned' count) 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?

States a specific verb and resource: it retrieves Merchant Center products together with their item-level issues (disapprovals, demotions, warnings) broken out per destination and the attribute to fix. This clearly distinguishes it in spirit from account-level issue tools, but it never names the sibling it differs from (e.g. merchant_account_issues or merchant_products), so the differentiation is only 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?

Usage is implied rather than stated: an agent can infer this is the item-level diagnostic scan and that merchant_plan_product_patch would follow to fix the returned attributes, but the description never says when to choose this over merchant_account_issues or when a plain merchant_products listing would suffice. No exclusions or prerequisites are given.

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 trailing 'Read only' adds little. What does add value is the pagination behavior (next_page_token for the next page), the 'processed view' framing, and the note that the returned id is the exact key merchant_plan_product_patch consumes. No auth or rate-limit context is given, but the safety profile is fully covered by annotations.

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