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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable operational context: it requires PERPLEXITY_API_KEY and costs cents per call, which is critical for an agent deciding whether to invoke the tool. It also clarifies it's an external API call. No contradictions with annotations.

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

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

The description is exactly three sentences, each with a distinct purpose: function, use case, and requirements/cost. It is front-loaded with the core action and contains zero filler. Every sentence earns its place, making it highly efficient.

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 4-parameter tool with no output schema, the description covers the purpose, required inputs, output (citations, domain presence, answer text), API key requirement, and cost. It does not detail error handling or response formatting, but given the annotations cover safety and the output is explicitly described, it is largely complete for an agent to invoke 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% – all four parameters are already described in the schema. The description ties 'question' and 'domain' together conceptually ('a question a customer might ask', 'whether your domain is among them'), but adds no additional syntax, formatting, or edge-case details beyond what the schema provides. 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 states a specific action (ask Perplexity's Agent API a question) and a specific resource (Perplexity's Agent API), and clearly enumerates the outputs: sources cited, whether your domain is among them, and the answer text. It also differentiates from alternatives by noting that ChatGPT and Google AI Overviews have no such API, making the tool's scope unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for when to use it: 'Useful to see if the site is being cited by AI search for target queries.' It also notes the limitation that only Perplexity offers this API, implying you cannot check other AI search platforms. It doesn't name a specific sibling tool as an alternative, but the context is sufficient for most agents.

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

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

The annotations already establish that the tool is read-only, idempotent, and non-destructive. The description adds meaningful behavioral detail beyond those annotations: it performs live HTTP requests with each bot's User-Agent, checks robots.txt at both root and URL levels, and can detect UA-based blocks like Cloudflare or WAF rules. This is valuable context that annotations alone do not provide.

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

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

The description is two dense sentences with no filler. The bot list and the citation-blocking consequence are informative rather than redundant, and the primary action is front-loaded. Every phrase adds useful detail for tool selection and invocation.

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 that there is no output schema, the description does a good job of conveying what the tool checks and why, including the robots.txt and live-request dimensions. However, it does not explicitly describe the return format or note that liveFetch=true may generate many per-bot requests, so a small gap remains.

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 input schema already covers both parameters at 100%, including the meaning of 'url' and 'liveFetch' with 'one request per bot'. The description reinforces these semantics but does not materially expand on them beyond naming specific bot UAs, so the baseline of 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 uses a specific verb and resource ('Check whether AI and search crawlers can reach a page'), enumerates the exact crawlers involved, and explains the two concrete mechanisms (robots.txt and live UA-based requests). It is clearly differentiated from generic robots checks and citation tools by naming the crawler-access scope and the consequence for assistant citation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context by stating that being blocked from certain bots means assistants cannot cite the site, which tells the agent when this tool is relevant. It does not explicitly name sibling alternatives like robots_check or ai_citation_check or give exclusions, but the intended use case is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds meaningful behavioral context beyond that: requires a paid PERPLEXITY_API_KEY, returns ranked results with title/URL/snippet/date, has no answer generation, and is cheaper and repeatable. No contradiction with 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?

Three sentences with no filler: the first states the core purpose, the second differentiates from the sibling and gives the strategic use case, and the third states the authentication requirement. Every sentence earns its place and key information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the rich schema with 100% parameter coverage, clear annotations, and the description's addition of API key requirement, return shape, cost profile, and repeatability use case, an agent has everything needed to select and invoke this tool correctly. No output schema exists, but the description lists the returned fields (title, URL, snippet, date), which is sufficient.

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

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

Schema description coverage is 100%, so the schema already explains all 8 parameters thoroughly. The description's parameter-related mentions ('up to 10 questions', 'your domain') repeat what the schema already states via maxItems and the domain parameter description. It does not add new parameter-level meaning, so 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 states a specific verb and resource: 'Ask Perplexity's Search API which pages it retrieves as sources' for up to 10 questions, and whether a given domain is among them. It names the sibling ai_citation_check and explicitly differentiates itself by returning only ranked results with no answer generation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context: it is for source-only, repeatable checks, tracking share of sources over time, and seeing which competitors AI search pulls from. It explicitly contrasts with ai_citation_check and states what this tool does NOT do ('no answer generation'), giving the agent a clear selection criterion.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, so the bar is lower. The description adds valuable behavioral context: it requires an external BRAVE_API_KEY, explains the pay-as-you-go cost model, and clarifies that results exclude your own domain and include link detection plus excerpts.

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 sentences pack the core purpose, key parameter guidance, and the critical API-key requirement without redundancy. The most important behavioral facts are front-loaded, and every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter tool with no output schema, the description covers the essential invocation details: required brand/domain, pagination, freshness, and external API key. It does not describe the exact return shape, but the purpose and key behaviors are sufficiently clear for an agent to call it correctly.

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

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

Schema description coverage is 56%, with brand, country, language, and checkLinks lacking descriptions. The description helps by clarifying brand ('brand name'), domain exclusion, freshness monitoring, and pagination, but it does not compensate for the undocumented country/language parameters or fully detail checkLinks 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 and resource: 'Search the web for pages mentioning a brand name that are not on your own domain, and check whether each mentioning page links to you.' This clearly differentiates the tool from siblings like ai_citation_check or ai_search_sources by focusing on brand mentions and outbound link detection.

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 concrete use cases: 'Unlinked mentions are outreach targets' and 'excerpts show in what context AI engines see the brand.' It also gives operational guidance for freshness and offset pagination, though it does not explicitly name alternative tools or state when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral detail beyond that: it returns the full redirect chain for each variant, identifies which variants are wrong, and states that no API key is needed.

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

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

The description is front-loaded with the core purpose, then briefly explains why the check matters, gives concrete context, and states the return value and auth requirement. Every sentence earns its place and there is no redundancy with the title or schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having no output schema, the description explicitly states what is returned ('full redirect chain') and what judgment is made ('says which ones are wrong'). Combined with the fully documented schema and strong annotations, an agent has everything needed to call and interpret this tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters and their formats. The description reinforces the 'home page' default and the domain scope, but it does not add meaningful semantics beyond what the schema provides, which matches the baseline for full 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 verb and resource: checking that all http/https, www/bare, and trailing-slash variants converge on one canonical address. It clearly distinguishes this from sibling tools by enumerating exactly which URL variants are tested.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for when this tool is useful, specifically calling out Cloudflare Pages and WordPress migrations as common failure scenarios. It does not explicitly name alternatives or exclusions, but the domain of canonical-host redirect checking is unambiguous enough that an agent can infer when to invoke it.

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

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

Annotations already establish that the tool is read-only, idempotent, and non-destructive. The description goes further by disclosing that it fetches multiple pages and computes a concrete list of metrics (fetch time, HTML size, term extraction, content-gap terms). This is sufficient behavioral context for a safe audit tool, though it does not mention network failure or latency 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?

The description is dense but efficient: one sentence lists the audit dimensions and a second explains the content-gap feature. It front-loads the core purpose before metrics, and there is no filler or repetition of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Since there is no output schema, the description carries the burden of explaining what the agent can expect. It lists the measured fields and the term-gap output in enough detail to set expectations. It does not describe error cases or output formatting, but for a read-only audit tool the listed output scope is largely sufficient.

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

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

The schema has 0% description coverage, so the description must compensate, but it only loosely maps to parameters. It explains the general idea of yourUrl and competitorUrls by mentioning 'yours plus pages ranking above you', and the content-gap phrasing hints at gapTerms, but it never explicitly defines gapTerms as the number of terms to return or explains the maximum of six competitor URLs. An agent would have to infer these semantics from names and schema constraints.

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 ('Audit') and resource ('several URLs side by side') and enumerates exactly what is compared: word count, headings, links, schema, etc. It also emphasizes the competitive angle ('yours plus pages ranking above you'), which clearly differentiates it from single-page audit tools like page_audit or pagespeed.

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 'yours plus pages ranking above you' gives a clear context: use this when you want a competitive content/SEO comparison against pages that outrank you. It does not explicitly name alternatives or state when not to use it, but the side-by-side framing is enough for an agent to select it over single-page audit siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false, so the safety profile is covered. The description adds the selection logic: period-over-period decline, staleness via sitemap lastmod, and lost queries. It doesn't mention output structure or behavior when sitemapUrl is missing, but that is a minor gap given the strong annotation coverage.

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 sentences, each earning its place: plain definition, detection mechanism, usage vs sibling, and concrete rewrite actions. There is no filler or repetition despite the first and second sentences being closely related.

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 analysis tool with no output schema, the description clarifies what kind of results to expect (declining stale pages plus the queries they lost), the core input semantics, and the decision context. It omits explicit return fields and details on default date ranges, but an agent can reasonably infer the output and invoke the tool correctly.

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

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

Schema coverage is only 33% (siteUrl, staleDays, and sitemapUrl have descriptions). The description gives context that maps to the period parameters ('between two periods') and to minPreviousClicks ('clicks or impressions dropped'), but top, the date-string params, and minPreviousClicks are not explicitly explained. It partially compensates for low coverage but doesn't fully document the remaining parameters.

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 starts with a plain-language definition ('Pages that used to perform and no longer do') and then states a specific verb and resource: 'Finds pages whose clicks or impressions dropped between two periods and that have not been updated recently (sitemap lastmod), with the queries they lost the most on.' It also differentiates itself from gsc_opportunities, so an agent can tell them apart 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?

It explicitly names the alternative and the decision rule: 'Use it for deciding what to rewrite; gsc_opportunities is for what to push over the line.' This gives clear when-to-use versus when-to-use-other guidance. It also adds actionable next steps for candidates, making the intended workflow concrete.

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

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

The annotations already indicate a safe read-only, idempotent, non-destructive operation. The description adds meaningful behavioral context: it only suggests links rather than creating them, and it optionally fetches top candidate pages to check for existing cross-domain links.

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 with no filler. The core purpose and scope are front-loaded, and the optional fetching behavior is stated efficiently in the second sentence.

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 analysis tool with no output schema, the description provides enough to understand selection and invocation: core inputs, purpose, and optional fetch behavior. Minor gaps around filtering parameters and return format remain, but the defaults and clear purpose prevent serious confusion.

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 only 43%, so the description must compensate. It clarifies siteA/siteB as owned properties on the same topic and mentions the optional candidate-page fetch, but it does not explain key parameters like startDate, endDate, minImpressions, or top. This is a meaningful, though partial, contribution.

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 and resource: find pages on two owned Search Console properties that rank for overlapping queries and suggest cross-links between them. This clearly differentiates it from sibling tools like gsc_opportunities or gsc_cannibalization by focusing on cross-site link suggestions.

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 explicitly states the context: for two Search Console properties the user owns on the same topic. It gives clear conditions for when the tool applies, though it does not mention alternative tools or exclusion cases.

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

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

Annotations already declare readOnly/openWorld/idempotent and non-destructive, so the description does not need to re-cover safety. It adds valuable behavioral context beyond annotations: it requires the Chrome UX Report API and one of the listed keys, returns 404 for low-traffic pages, and has a ~25-week history window.

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

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

The description is concise and front-loaded: the first sentence communicates the core function, metrics, and output; the subsequent sentences add routing, prerequisites, and an error-handling hint. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description rightly explains the return shape: weekly p75 values and good/needs-improvement/poor shares for each metric. It also covers authentication, error behavior, and the distinction from crux_snapshot, making the tool callable without guessing, though exact date/time-series formatting and pagination are not specified.

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

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

Schema coverage is 50%, with descriptions for target and formFactor but not scope or weeks. The description partially compensates by explaining the origin-or-URL input and weekly time span, but it does not clarify how the weeks parameter interacts with the mentioned ~25-week window or define the scope enum semantics beyond the parameter name.

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: it returns a real-user Core Web Vitals trend (LCP, INP, CLS, FCP, TTFB) from the CrUX History API for an origin or URL, including weekly p75 values and quality-bucket shares. It clearly distinguishes itself from the sibling crux_snapshot by saying to use crux_snapshot for the latest record and LCP sub-part breakdown.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly tells the agent when to choose crux_snapshot instead (latest record, LCP sub-part breakdown) and gives a remediation path for the 404 low-traffic case: fall back to the origin. It also states the required API enablement and credential key names, so there is little ambiguity about prerequisites versus 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 readOnly/openWorld/idempotent/non-destructive, so the bar is lower. The description adds value beyond those by disclosing the required API key setup, the NOT_FOUND error meaning and the scope fallback, and by clarifying that the data is a 28-day real-user aggregate. No contradiction with 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?

Although dense, every clause adds information: metrics returned, LCP breakdown purpose, nav mix, sibling routing, auth, and error handling. The main purpose is front-loaded in the first clause, and 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, so the description carries the burden of explaining return content; it names the metric set, the LCP sub-part phases, the element type, and navigation mix. It also covers prerequisites and a common error path. This is sufficient for an agent to know what the tool returns and when to call it.

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

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

The schema already covers 100% of parameters with descriptions, including enum meanings and defaults, so baseline 3 applies. The description reinforces scope choice with the 'try scope=origin' fallback but does not materially extend the schema's parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens by naming the resource ('Chrome UX Report'), the temporal scope ('latest 28-day'), and the level ('origin or URL'), then enumerates the returned metric families. It explicitly contrasts with crux_history, so an agent can distinguish it from its only sibling. This is a clear verb+resource+scope definition.

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 an explicit alternative: 'Use crux_history for the weekly trend,' which tells the agent when to prefer the sibling. It also provides operational direction for low-traffic results ('NOT_FOUND means too little traffic, so try scope=origin') and prerequisite auth requirements, making invocation conditions clear.

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 behavior, so the description doesn't need to restate safety. It adds useful behavioral detail beyond annotations: it checks a sample of articles and returns a pass/fail checklist with additions, which clarifies what the agent will receive.

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

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

The description is a single, information-dense sentence that front-loads the resource type and lists concrete checks before stating the return value. No filler or repetition exists, though the long enumeration could be slightly restructured for readability without losing value.

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 audit tool with no output schema, the description covers the essential context: what is checked, what is returned, and the sampling behavior. It does not mention potential performance or sampling limits, but those are minor given the annotations and schema constraints.

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

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

Schema description coverage is 0%, so the description must compensate. It explains sampleArticles by mentioning 'a sample of articles checked for bylines and dates,' but does not elaborate on the integer's range or effect. siteUrl is self-evident and the schema already provides the URI format, so the partial compensation is acceptable but not complete.

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 resource ('site-level trust signals') and a clear outcome ('Returns a pass/fail checklist with what to add'). It enumerates concrete checks (About/Contact pages, schema, HTTPS, author pages, etc.), which distinguishes it from page-level or schema-only audits in the sibling 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?

The description clearly implies when to use it: when an agent needs a site-wide E-E-A-T trust audit. It does not explicitly name alternatives or state when not to use it, but the site-level scope and detailed checklist give enough context to select it over page-level or schema-specific siblings.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the description does not need to repeat those. It adds value by disclosing the 'same property' constraint and that results are returned 'in order' per report, which is behavioral context not present in annotations. No contradiction with 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?

Two sentences with no filler. The purpose is front-loaded, the key constraint (same property) is stated early, and the reference to ga_run_report's core is a compact way to convey parameter semantics. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a batch wrapper with an existing single-report sibling, the description is adequate: it states the batching limit, the property constraint, and the return format. It does not detail error handling or partial failure behavior, but the schema documents the report structure. Given the annotations cover safety and the schema covers parameter structure, this is sufficiently complete for an agent to invoke 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?

The description lists the core fields (dimensions, metrics, startDate, endDate, dimensionFilters, metricFilters, limit, offset) and references ga_run_report for their semantics, which helps an agent familiar with that tool. However, schema description coverage is only 50% and the description does not compensate for undocumented fields like name, filterLogic, or matchType. It relies heavily on the schema to fill gaps, which is adequate for a batch wrapper but not exemplary.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Run'), a resource ('up to 5 standard reports'), and a key constraint ('same property'). It explicitly differentiates from siblings by referencing ga_run_report's core fields and using 'standard reports' to exclude realtime/pivot/funnel variants. The purpose is unambiguous and no sibling could be mistaken for this 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 clearly implies this is for batching multiple standard reports in one call, and by referencing ga_run_report's core it signals the single-report alternative. However, it does not explicitly state 'use this instead of ga_run_report when you need multiple reports' or list when not to use it. The batch intent is clear but exclusion criteria are 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 readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds that the tool queries GA4 for compatibility and returns compatible additional fields, which is useful but does not go into details like return shape, pagination, or error 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?

The description is two sentences with no filler. The core action is front-loaded, and the usage guidance is placed immediately after the functional explanation.

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 compatibility check, the description provides the essential context: what it checks, what it returns conceptually, and when to use it. There is no output schema, so a little more detail about the response format or the effect of onlyIncompatible would be helpful, but the description is still sufficient for basic invocation.

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

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

Schema coverage is only 50%; metrics and dimensions lack schema descriptions. The description does explain that these parameters represent 'a set of dimensions and metrics' checked for compatibility, but it does not fully compensate by clarifying formats, allowed values, or edge cases like empty arrays.

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 and resource: 'Ask GA4 whether a set of dimensions and metrics can be queried together' and 'which additional fields are still compatible.' It clearly differentiates itself from the sibling ga_run_report by saying 'Use before building an unusual ga_run_report.'

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 a clear usage context: use before building an unusual ga_run_report. It does not explicitly list alternatives or when-not-to-use scenarios, but the context is specific enough for an agent to select this tool appropriately.

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, covering the safety profile. The description adds value by explaining the return structure (per-row current/previous/delta/percent change plus period totals), but it does not mention pagination, rate limits, or any other behavioral quirks. It provides some additional context beyond the annotations, but not a rich behavioral picture.

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

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

The description is two sentences with no fluff. It front-loads the main action, states the output, and gives a concrete example. Every sentence earns its place, and the structure is efficient and clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (12 parameters, no output schema), the description is incomplete. It does not explain how to set date ranges, what metrics are valid, how filters work, or provide a detailed output format beyond a summary. The lack of an output schema and the minimal parameter guidance leaves significant gaps for an agent attempting to call this tool correctly.

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

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

Schema description coverage is only 42%, so the description should compensate for undocumented parameters. It only mentions the dimensions default (channel group) and does not explain date range parameters (currentStart, previousStart, etc.), metrics, or filter options. The schema provides some descriptions for limit, propertyId, filterLogic, and filters, but the description adds almost nothing beyond that. The low coverage and lack of description compensation make this a weak area.

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 action (compare GA4 metrics) with a specific resource (between periods) and describes the output (per-row changes and totals). It distinguishes itself from general GA4 reporting tools by focusing on period-over-period comparison, and it gives a concrete use case. It is not a tautology and provides enough specificity to be unique among siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear example of when to use the tool ('how did organic traffic change vs last month'), which implies a period-over-period comparison scenario. However, it does not explicitly mention when not to use it or name alternative tools (e.g., ga_run_report for single-period reports). The guidance is clear but could be more explicit about exclusions.

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, covering safety. The description adds valuable behavioral context: it returns custom dimensions/metrics, metric types (TYPE_SECONDS, etc.), and deprecated API names. It does not contradict annotations and enriches the agent's understanding of what to expect from the 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?

The description is a single, dense sentence that front-loads the main purpose (listing dimensions/metrics) and then adds key details (custom ones, types, deprecated names, filtering). Every word earns its place; there is no fluff or repetition. It is concise and well-structured.

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 metadata listing tool with strong annotations (read-only, idempotent) and no output schema, the description is fairly complete. It explains the content (dimensions, metrics, types, deprecated names) and the filtering mechanism. It does not mention pagination or result limits, but these are not critical for such a tool. The description covers the essentials an agent needs to call it correctly.

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

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

Schema description coverage is 67% (search and propertyId are described; kind has an enum and default but no description). The description adds a small hint about using search to keep output small, which complements the schema's already-detailed search description. However, it does not explain the 'kind' parameter beyond its enum values, and the schema already covers most semantics. 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 clearly states the verb ('List') and the resource ('dimensions and metrics available for a GA4 property'), and specifies details like custom ones, metric types, and deprecated API names. It distinguishes itself from siblings like ga_run_report (which runs reports) and ga_list_properties (which lists properties) by focusing on metadata. This is a precise, actionable definition.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains what the tool does but does not explicitly state when to use it versus alternatives. It mentions filtering by search to keep output small, which implies usage for exploration, but there is no direct guidance on when not to use it (e.g., for data retrieval) or naming alternative tools. This leaves the decision to the agent's 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 indicate a safe read-only, idempotent operation. The description adds useful behavioral context beyond that: it merges data from two separate sources, focuses on organic-search sessions, and requires matching properties. It does not disclose error handling for mismatched properties or date-format constraints, but the core behavior is well stated.

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

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

Two sentences, no filler. The first sentence front-loads the output and contents; the second states the prerequisite. Every clause earns its place and the description is easy to parse quickly.

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 merged-report tool with 6 parameters and no output schema, the description covers the output shape (table per landing page), the metric groups, and the required property pairing. It omits details like date formats and limit behavior, but the overall invocation context is sufficiently complete for an agent to select and call it correctly.

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

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

With schema description coverage at only 33%, the description partially compensates by clarifying that the date range applies to both data sources and that each output row corresponds to a landing page. However, it does not explain limit, sortBy, or startDate/endDate formats; the schema only provides defaults and enums. The description adds some meaning but leaves several parameters to inference.

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 deliverable: one table per landing page combining GA4 organic-search metrics with Search Console performance for the same period. This clearly distinguishes the tool from siblings like ga_run_report (GA4 only) and gsc_search_analytics (Search Console only), because it explicitly merges both data sources.

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 a clear prerequisite: both the GA4 property and the Search Console property of the same site must be provided. This effectively tells an agent when the tool is appropriate. It stops short of explicitly naming alternatives or stating when not to use it, but the context is strong enough for correct selection.

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 description doesn't need to repeat those. It adds valuable context by noting the prerequisite that the Analytics Admin API must be enabled and that the listing is scoped to the authorized account, which goes 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?

Two concise sentences: the first states the core action and resource, the second adds a necessary prerequisite. No filler or redundancy; every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with no parameters and safety annotations, the description is sufficiently complete. It specifies what is listed and the API requirement. It doesn't mention output format or pagination, but these are minor for a tool of this simplicity.

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

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

There are zero parameters, so the schema has full coverage and no parameter documentation is needed. The baseline for 0 params is 4, and the description doesn't need to add anything about parameters since none exist.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('List'), a precise resource ('Google Analytics accounts and GA4 properties'), and the scope ('the authorized account can access'). It is unambiguous and clearly differentiates from sibling tools like ga_run_report, which run reports rather than list resources.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies its use for discovery of accessible accounts/properties, but it does not explicitly contrast it with alternatives or state when not to use it. The context is clear enough for an agent to infer the purpose, but no explicit routing guidance is 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, idempotentHint=true, destructiveHint=false, so the description's 'Read' aligns. It adds valuable context beyond annotations by explaining what each section contains (e.g., 'attribution model and lookback windows (why key events disagree with Search Console or Ads)' and 'Google Signals state (what makes reports subject to thresholding)'), enriching behavioral understanding of output semantics. No contradiction.

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

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

The description is moderately long but front-loaded with the core action and then efficiently lists the section categories. Each sentence earns its place, and the optional sections are clearly separated. It could be slightly tighter (e.g., bullet list), but it is well-structured and not repetitive.

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 only 2 parameters, no output schema, and comprehensive annotations (readOnly, idempotent, openWorld), the description covers what the tool returns by listing all sections and their purpose. It even provides explanatory reasoning for why sections matter (e.g., attribution and thresholding). Missing details like return format are not critical given no output schema. Complete for practical use.

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 50% (only propertyId has a description). The tool description compensates by explaining the meaning of the sections parameter (listing all allowed values and their contents) and giving an example for propertyId. This goes beyond the schema's bare enum and default, adding semantic value for both parameters.

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 clear, specific action ('Read a property's setup') and enumerates the exact configuration categories included (details, retention, streams, custom dimensions/metrics, key events, ads links, audiences, attribution, Google Signals) plus optional sections. This distinguishes it from siblings like ga_run_report (data queries) and ga_get_metadata (metadata). It is unambiguous and precise.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by enumerating what the tool reads and adds 'Choose sections to keep the output small,' which guides on how to tailor calls. It does not explicitly name alternatives or state when not to use, but the purpose is so specific that an agent can infer appropriate use cases. Lacks an explicit exclusion clause.

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 description doesn't need to cover safety. It does add value by explaining open vs closed funnels and the 'nextAction' behavior, which are not in the schema, but could be more explicit about response structure or edge cases.

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

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

The description is a compact paragraph that covers critical concepts and an example, without excessive detail. It could be slightly more structured with bullet points, but it effectively front-loads the core funnel concept and example.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the essential behavioral aspects of a complex funnel tool, including step configuration, open/closed modes, and optional analysis layers. It lacks mention of some advanced parameters like 'filterLogic' but the schema covers them. Overall sufficient for an experienced GA4 user.

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 69%, and the description explains key parameters like 'closed' and 'nextAction' beyond the schema, but leaves some parameters (like 'filterLogic') to schema definitions. It adds value but doesn't fully compensate for the uncovered parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool runs a GA4 funnel report, defining what it measures (users reaching steps, drop-off) and even provides a concrete example of the steps structure, distinguishing it from siblingreport tools by its specific funnel focus.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context via the example and optional parameters, but doesn't explicitly state when to use this vs. alternatives like ga_run_report or ga_run_pivot_report. It provides clear functional context but lacks explicit exclusions or 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?

With annotations already declaring readOnlyHint, idempotentHint, and destructiveHint=false, the safety profile is covered. The description adds useful behavioral context by promising a matrix plus row totals and saying the tool builds the two pivots, but it does not disclose pagination behavior, how limits truncate the matrix, or what happens when filters are applied.

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 tightly written sentences, with the operation stated first, a concrete example, and the key output shape. Every clause earns its place and there is no fluff.

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 11-parameter tool with no output schema and 27% schema coverage, the description is too thin: it omits the required propertyId, date handling, filter behavior, pagination semantics, and does not route the agent among closely related sibling report tools. An agent could call the defaults, but it would not know how to configure the tool correctly for non-default cases.

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 description maps the core parameters to concrete examples (landingPage rows, deviceCategory columns, sessions metric), adding meaning to parameters that lack schema descriptions. However, schema coverage is only 27% and the description leaves dates, limits, pagination, and dimensionFilters unexplained, so it only partially compensates.

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 and resource ('Cross-tab one dimension against another' in GA4) and clarifies the result as a matrix with row totals, so the tool's purpose is unmistakable. It does not explicitly contrast with sibling tools like ga_run_report, but the pivot semantics inherently distinguish it from a flat GA4 report.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool ('give rowDimension, columnDimension and metrics') and positions it as simpler than the raw API, but it never names alternatives or states when not to use it. Sibling tools such as ga_run_report or ga_run_funnel_report are not mentioned, so the selection guidance 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so safety is covered. The description adds behavioral details beyond annotations, such as default sorting by the first metric unless orderBy overrides, and enumerates supported dimensions and metrics.

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

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

Three sentences with no fluff. The main purpose is front-loaded, followed by allowed values and sorting behavior. Every sentence adds value.

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, idempotent tool with annotations covering safety, the description provides the key dimensions/metrics and default sort. No output schema exists, but the listed fields imply the return shape. The minuteRanges parameter is described in the schema, so nothing critical 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 63%, leaving some parameters undocumented. The description compensates by listing allowed dimension and metric values, which the schema does not provide as enums. It also reinforces the default sorting behavior mentioned in the orderBy description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves real-time (last 30 minutes) GA4 data, lists the available dimensions and metrics, and notes default sorting. This distinguishes it from sibling GA tools like ga_run_report (historical) and ga_run_pivot_report.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for real-time data via the 'Real-time (last 30 minutes)' qualifier, which contrasts with historical tools. However, it does not explicitly name alternatives or state when not to use it, leaving some inference required.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds genuinely useful behavioral detail: optional comparison range vs up to 4 explicit dateRanges, and the caveat that dataQuality is returned when rows were thresholded, sampled, or rolled into '(other)'. No contradiction with annotations.

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

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

The description is three dense, purposeful sentences. Common dimensions and metrics are front-loaded, and every sentence adds value: range options, metadata pointer, and dataQuality warning. There is no filler or redundancy.

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 18-parameter read-only tool with no output schema, the description covers the essential invocation surface: valid dimensions/metrics, date-range behavior, and sampling/thresholding warnings. It does not fully document filters, ordering, or return shape, but the schema covers structural details and the core usage is clear enough for an agent to call it correctly.

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

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

With schema description coverage at 61%, the description helps by enumerating valid dimension and metric names and explaining the date-range modes. It does not, however, clarify filter semantics, orderBy behavior, or how comparison parameters map to output, so it only partially compensates for the schema gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies this as a GA4 Data API reporting tool and lists the common dimensions and metrics an agent would need to invoke it. However, it does not explicitly distinguish itself from sibling GA tools like ga_run_pivot_report, ga_run_realtime_report, or ga_compare_periods beyond the generic 'Data API report' framing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies core GA4 reporting usage and correctly points to ga_get_metadata for discovering more metrics, which is useful routing guidance. But it never explicitly states when to choose this over the pivot, realtime, funnel, or comparison-period siblings, leaving selection largely 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 readOnly/idempotent annotations, the description reveals behavior not visible in schema: it returns five judgment categories, explains the match is lexical not semantic, notes a 60-word buried threshold, and describes question-shape checking for figures/steps/lists. It is consistent with readOnlyHint; even the faqDraft is only a draft, not a publish action.

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

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

The description is dense but every sentence carries information: the purpose, the key statuses, the lexical-match caveat, the shape flags, and the data-source rule. The most important scoping detail (reads page body, not headings) is front-loaded.

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 return semantics, and it does well by enumerating statuses and the extracted-answer behavior. It only slightly under-specifies the exact response structure an agent should expect, but for a complex multi-status tool this is 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 coverage is 100%, so the schema already documents all 9 parameters. The description reinforces the relationship between questions and pages and the Search Console source, but adds little parameter-specific 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 states a clear verb + resource: it reads the page body and judges, per question, whether an AI can extract an answer, listing the exact statuses. It also distinguishes itself from gsc_question_queries, so an agent can tell them apart 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?

The description names the sibling alternative (gsc_question_queries) and states the difference: that check only looks at headings, while this tool reads the body. It also clarifies when questions come from Search Console vs. when to pass custom questions with pages, giving concrete invocation context.

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. The description adds valuable context beyond these by listing the exact signals analyzed (FAQ schema, E-E-A-T, outbound citations, etc.) and disclosing the return payload (score, signals found, and concrete fixes). This gives the agent a clear picture of what the tool does internally.

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

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

The description is compact and front-loaded: the first sentence opens with the main verb and purpose, then efficiently lists the evaluation criteria, and the second sentence states the return values. Every phrase adds useful information without fluff or repetition.

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 single-url, read-only scoring tool, the description covers the input, the process, and the output clearly. It lists the page attributes examined and the concrete returns (score, signals, fixes). Minor omissions like score interpretation or accessibility prerequisites are acceptable given the tool's simplicity and the absence of an output schema.

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

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

Schema description coverage is 0%, so the description must compensate for the undocumented url parameter. It only implicitly ties the parameter to 'a page' without explicitly stating that the url should be the page to score or specifying format constraints. Since there is only a single, self-explanatory parameter, the gap is small, but not fully bridged.

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 ('Score'), identifies the resource (a page's GEO readiness for AI answer engines), and enumerates concrete evaluation signals. It clearly distinguishes this tool from generic audits like page_audit or eeat_audit by focusing on extractability/citability by ChatGPT, Perplexity, and Google AI Overviews.

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 clearly implies the use case: use this when you need a 0-100 GEO readiness score and insights into how AI answer engines can extract and cite a page. However, it does not explicitly name alternative tools or state when not to use it, so it falls just short of full 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?

While annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds valuable behavioral context beyond that: it explains the polling behavior of waitSeconds (waits until everything finishes instead of a pending snapshot) and discloses a host-specific quirk (Cloudflare Pages on this setup reports nothing, so checks alone stay empty). This goes beyond the annotation coverage and helps the agent understand edge cases.

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

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

The description is compact (four sentences) and front-loaded with the core purpose, immediately followed by the critical usage sequence. Every sentence serves a function: purpose, usage order, waitSeconds behavior, and read-only nature. There is no filler or repetition beyond the redundant 'Read-only' which aligns with the annotation but is harmless.

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 status tool with no output schema, the description is remarkably complete. It specifies what data it returns (GitHub Actions check runs, combined commit status, deployments with latest state), when to call it, how the polling works, and even a host-specific caveat (Cloudflare Pages not reporting). It covers all the operational context an agent needs to invoke it correctly and 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 all six parameters are already documented in the input schema with detailed descriptions. The tool description adds minimal extra parameter meaning—only a brief note about waitSeconds polling behavior, which is partially redundant with the schema's 'Keep polling until every check and deployment settles.' The baseline of 3 is appropriate since the schema does the heavy lifting and the description doesn't compensate for any gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: to report whether a site actually built and went live after a commit, listing the specific sources (GitHub Actions, commit status, deployments). It also distinguishes itself from siblings by naming the exact calling sequence relative to github_commit_files and IndexNow/Google Search Console. This is a specific verb+resource with clear scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly instructs when to call: 'Call it after github_commit_files with the sha it returned, before submitting the URL to IndexNow or inspecting it in Search Console.' This provides a concrete ordering and references sibling tools, leaving no ambiguity about context. It also explains the waitSeconds parameter's purpose for polling until completion.

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 (destructiveHint=true, openWorldHint=true, non-idempotent, not read-only), so the bar is lower. The description still adds real context: server-side-only processing ('Nothing passes through the client') and precisely what dryRun returns (attachment, resulting dimensions and bytes) without committing. It stops short of stating overwrite behavior at an existing path.

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 sentences, zero waste. The core action is front-loaded and the dryRun behavior is placed last as a secondary mode, which matches how an agent will read it.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex 15-parameter image-conversion-and-commit tool with no output schema, the description covers the pipeline, the server-side processing, and the dryRun reporting mode well. It leaves minor gaps around createBranch and path-collision semantics, but nothing an agent needs to invoke it correctly is fundamentally 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 67% and the schema already documents width/height, focus, variants, convert and format richly. The description reinforces those concepts ('webp by default, cover-crop, variants') but adds little semantic detail beyond the structured fields, so the baseline 3 is appropriate. It does not clarify undocumented params like createBranch or quality.

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 (commit), the source resource (a Gmail attachment), and the destination (a repo branch), and names the upstream sibling gmail_find_attachments. The scope is distinct from github_commit_files/github_commit_image because it takes the bytes straight from Gmail with nothing passing through the client, so an agent can tell it 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 implies the workflow clearly by pointing at gmail_find_attachments as the way to obtain the messageId/filename, and it explains the dryRun preview path. However it never says when to prefer this over the related commit siblings (github_commit_files, github_commit_image) or any when-not-to-use condition, leaving routing 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 flag destructive and non-idempotent, and the description adds meaningful context beyond them: commits are atomic, edits apply in order against the branch's current content and require an exact single match unless all=true, the file must exist and be text, and dryRun validates matches and reports sizes/changed-line counts without committing.

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 otherwise dense with no filler; two sentences carry a lot of required detail. The sentences run long, but every clause earns its place by describing a distinct per-file mode or flag.

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, multi-mode mutation tool with no output schema, the description supplies the mode selection rules, atomicity, exact-match semantics, branching behavior, and dry-run validation an agent needs to invoke it correctly.

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

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

Schema coverage is 83%, so the baseline is 3, but the description adds real meaning: encoding=base64 is for binary files, edits is find/replace with single-match requirement, createBranch seeds from the default branch, and dryRun previews per-file action, sizes, and changed-line counts. It leaves a few details (e.g., maxItems limits, required path) to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('atomic commit that adds, updates, edits or deletes several files on a branch') and names the underlying mechanism (Git Data API) plus the downstream effect (CI/CD deploys). This distinguishes it from siblings like github_get_file, github_commit_image, and github_commit_attachment.

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 per-mode routing: 'per file give exactly one of content ... edits ... or delete', and clarifies edits is 'right for large files such as a 300 KB content bundle'. It also explains createBranch and dryRun usage. It stops short of stating when to prefer this tool over the specialized siblings (image/attachment committers).

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 destructiveHint=true, openWorldHint=true and idempotentHint=false. The description adds meaningful context beyond them: everything runs server-side (nothing on the client), all outputs land in a single commit, and dryRun commits nothing. It doesn't detail overwrite/conflict behavior or auth needs, keeping it below 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 dense sentences that front-load the main action, then the server-side guarantee and the dryRun workflow. No filler or repetition.

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 13-parameter, destructive, no-output-schema tool, the definition covers the essential mechanics: source URL, conversion, single-commit behavior, dryRun preview, and the follow-up sibling. Minor gaps remain around overwrite/branch-conflict behavior, but overall it is well-covered.

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 69%, so the schema documents most parameters. The description reinforces the dryRun purpose and format default and gives a concrete variant example, but adds little syntax/format detail beyond the schema for the other parameters (focus, quality, createBranch).

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 specific verbs and resource: downloads an image, converts (webp default), resizes/cover-crops, and commits outputs to a GitHub branch in one commit. It clearly distinguishes itself from github_commit_files by naming that sibling as the follow-up code-editing step.

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 workflow guidance: use dryRun first to preview dimensions/bytes, then register the file with github_commit_files (edits). This routes the agent between sibling tools well, but it does not state when NOT to use this tool or address branch/overwrite 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 signal read-only, idempotent, non-destructive behavior. The description adds substantial behavioral context: large files are handled via the blob API, responses are capped by maxBytes, pagination is done through nextOffset, binary files are refused, and the returned fields are enumerated. This goes well beyond the annotations without contradicting them.

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

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

The description is compact and well structured: it opens with the core action and return shape, then covers large-file behavior, pagination, and the editing alternative in a single dense sentence. Every clause adds necessary information and no content is redundant with the schema or annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description covers the return contract (content, sha, size, URL), explains the pagination mechanism, notes the size limits, and warns about binary files. An agent has enough context to call this tool correctly or route to github_commit_files when appropriate.

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

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

The schema already documents all 5 parameters at 100% coverage, so the baseline is 3. The description adds value by framing offset and maxBytes as a pagination workflow and explaining why a large file should not be read entirely, which helps an agent choose appropriate values. It does not fully replace the schema, but it deepens understanding of the parameter interaction.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Read a text file from a repository branch') and lists the return fields ('content, sha, size and the file's URL'). It clearly distinguishes itself from siblings like github_list_dir and github_search_code, and the explicit 'Binary files are refused' sharpens its scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear directional guidance: use this for reading text files, avoid binary files, and when the goal is to edit a huge file, use github_commit_files instead of reading it whole. This explicitly names an alternative and an exclusion condition, which is more than most tool descriptions provide.

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 the safety profile is covered. The description adds that results are ordered by recency and can be filtered by path, but it does not disclose pagination behavior, default limits beyond the schema, or return shape.

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

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

A single, front-loaded sentence that immediately tells the agent what the tool returns and the key optional scoping. There is no filler or repeated schema 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 simple read-only list operation, the description plus annotations are adequate for basic selection and invocation. However, there is no output schema and no description of the returned commit fields, ordering guarantees beyond 'recent', or how limit interacts with pagination, leaving moderate gaps.

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 only 25% (only repo is documented). The description mentions branch and path as filtering dimensions but does not explain their value formats, defaults, or relationships. The limit parameter is entirely unaddressed, so the description does not sufficiently compensate for the low schema 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 states a specific verb and resource: it lists recent commits and scopes them by branch and optional path. It does not explicitly differentiate itself from sibling tools like github_commit_files or github_list_dir, though the resource being returned is clearly commits.

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 context is implied: use it when you need recent commits for a branch, optionally filtered by path. However, it provides no explicit when-not-to-use guidance, no mention of alternatives, and no note about when the path filter would be preferable to other search 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, openWorldHint, idempotentHint, and non-destructive behavior. The description adds useful context beyond those annotations by naming the exact output fields (name, type, size, sha) and clarifying that it lists both files and folders at a given path. This is meaningful but not extensive.

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

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

The description is a single, front-loaded sentence with no filler. Every part contributes meaning: the action, the resource, and the response fields. It is appropriately sized for a simple listing tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is adequate for a basic call with just 'repo', and the output fields are mentioned. However, it omits key context such as what 'ref' means, how 'path' behaves when omitted, and any pagination or default-branch behavior. Since there is no output schema, those details would materially improve completeness.

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 only 33%, and the description does not compensate for the undocumented optional parameters. In particular, 'ref' is not explained as a branch/tag/commit SHA, and 'path' semantics are only vaguely implied by 'at a path'. The description adds little value beyond the parameter names themselves.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('List') and resource ('files and folders at a path in a repository'), and includes the returned metadata fields. It does not explicitly differentiate from siblings like github_get_file, though the listing-vs-content distinction is reasonably 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?

The description implies when to use it — when you need a directory listing — but gives no explicit guidance about when not to use it or which sibling tool might be a better fit. An agent can infer usage, but the description leaves that inference unstated.

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 tool read-only, idempotent, and non-destructive. The description adds meaningful behavioral context: results include matching files with fragments, and the index only covers the default branch—an important limitation that affects expectations. No contradiction with 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?

Three short sentences front-load the core action, then add syntax examples, return shape, and the key indexing caveat. Every sentence earns its place and 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?

For a simple search tool with no output schema, the description covers what is returned, the scope, and the most important behavioral limitation. The schema covers required parameters and the limit constraint, while annotations cover safety and idempotence. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema description coverage is low at 33%, but the description partially compensates by giving concrete query syntax examples such as 'og:image path:src' and 'canonical extension:astro.' It does not add meaning to the repo or limit parameters beyond what the schema already provides via pattern, default, and range.

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: 'Search file contents in one repository.' The examples of GitHub code search syntax make the operation concrete, and the phrase 'Returns matching files with fragments' differentiates it from sibling file tools like github_get_file or github_list_dir.

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 clear context for when to use the tool: searching file contents within a single repository, with GitHub code search syntax. It does not explicitly name alternatives or exclusions, but the scoping phrase 'in one repository' and the 'default branch only' caveat make routing unambiguous.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only safety profile is covered. The description adds valuable behavioral context beyond annotations: default only messages with attachments are returned, requireAttachment=false changes the implicit 'has:attachment' filter, and only a ~200-character snippet is shown — a real limitation an agent needs to know.

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 compact sentences pack purpose, usage context, search syntax, default behavior, and a key output limitation without redundancy. Every clause earns its place and the most decision-relevant information is front-loaded.

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 tool with no output schema, the description covers purpose, selection criteria, parameter behavior, and an output limitation (snippet length). It doesn't describe the full return payload structure, but the description already enumerates the key attachment fields, so an agent has enough to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes further by explaining the purpose of requireAttachment (finding body-text messages to read via gmail_get_message) and giving concrete query examples like 'from:alba newer_than:14d', adding meaning beyond the schema's brief parameter descriptions.

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?

Description names a specific verb, resource, and outcome: search the authorized Gmail mailbox and list matching messages with attachment details (name, type, size). It also frames the practical purpose — committing an emailed photo/document to GitHub — and distinguishes itself from gmail_get_message, a sibling that reads a single message's body.

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 explicit usage context: when you need an attachment for a GitHub commit, use this tool; when the content is in the email body instead, set requireAttachment=false and read it with gmail_get_message. It even includes Gmail search syntax examples, leaving no ambiguity about when this tool is the right choice.

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 valuable behavioral context beyond annotations: the fallback behavior from text/plain to HTML-stripped-to-text, the maxChars truncation behavior, and the security warning to treat content as untrusted third-party data. It doesn't describe pagination mechanics in detail, but the offset parameter description covers that. No contradiction with 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?

Four sentences, each earning its place: the first states the core function and fallback, the second gives the use case and sibling distinction, the third explains truncation and pagination, and the fourth is a security warning. The most important information is front-loaded. 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?

For a read-only tool with full schema coverage, no output schema, and annotations covering safety, the description is complete. It covers what the tool returns (headers plus body), how it handles HTML fallback, how truncation works, how to get more content (offset/nextOffset), and the security posture. An agent has everything needed to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds meaning beyond the schema by explaining the fallback behavior ('falling back to the HTML part stripped to text') and the truncation semantics ('Long bodies are cut at maxChars: raise it or page through with offset'). It also clarifies the relationship between messageId and gmail_find_attachments. This goes beyond the baseline 3 for full schema 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 states a specific verb ('Read'), a specific resource ('one Gmail message in full'), and the exact scope (headers plus decoded text/plain body, falling back to HTML stripped to text). It also distinguishes itself from gmail_find_attachments, which only returns a ~200-character snippet, so an agent can tell them apart 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 description explicitly says when to use this tool ('This is how text that arrived by email ... becomes usable here') and names the alternative (gmail_find_attachments) with the condition that selects it (only returns a snippet). It also gives guidance on long bodies: raise maxChars or page through with offset. This is clear when-to-use and when-not-to-use 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 establish read-only, idempotent, and non-destructive behavior. The description adds value by disclosing what the tool inspects: which credentials are active and whether a token can be obtained, which is useful diagnostic 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?

Two tight sentences, front-loaded with the purpose and immediately followed by practical usage advice. No filler or redundant restatement of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple zero-required-parameter read-only check, the description gives enough context about what is verified and when to call it. The only minor gap is the undocumented verbose flag, which also affects parameter semantics.

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 only parameter, verbose, has a boolean type in the schema but 0% description coverage, and the description never mentions it. The name suggests it controls output verbosity, but the agent receives no guidance on its actual effect or default 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?

Clearly states a specific action: verify which Google credentials are in use and whether an access token can be obtained. This distinguishes it from the sibling audit and analytics tools, which perform completely different functions.

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 tells the agent to 'Run this first if other tools fail', giving a clear when-to-use trigger. It does not discuss when not to use it or alternatives, but this is less critical given that no sibling duplicates this auth-checking role.

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 indicate this is a write operation and is not idempotent. The description adds meaningful behavioral context beyond that: ownership verification is not handled by the API and must be completed in the Search Console UI before data appears. This prevents the agent from assuming immediate data availability after calling the tool.

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

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

The description is compact and front-loaded, stating the core action in the first sentence. The additional sentences each add necessary constraints or expectations without any filler or redundancy.

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 single-parameter tool with no output schema, the description covers the input format, the API limitation, and the required post-call verification step. It does not describe potential errors or idempotency behavior, but those are partly covered by annotations and are less critical given the small surface area.

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 single siteUrl parameter is already described with its URI format. The description adds value by reinforcing the required trailing slash, providing a concrete example, and specifying that only URL-prefix properties are accepted, which directly informs how to construct the parameter value.

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 precise verb and resource: adding a URL-prefix property to the authorized account's Search Console. It also clarifies the exact property type and distinguishes itself from domain properties and from sibling tools like gsc_list_sites and gsc_delete_site.

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 clearly conveys when this tool is appropriate: adding URL-prefix properties. It also gives an explicit exclusion ('Domain properties cannot be added through the API') and explains that verification must happen in the UI, which sets expectations for follow-up steps. It does not name alternative tools directly, but the usage context is otherwise clear.

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/openWorld/idempotent safety, so the description only needs to add operational behavior. It does: each result lists competing pages with clicks, impressions, and position, and it implies a follow-up action (consolidate or differentiate). No contradiction with 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?

Two sentences, front-loaded with the trigger condition and ending with the output format and intended action. Every sentence earns its place; 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, so the description correctly takes on the job of explaining return values: competing pages plus clicks, impressions, and position. It does not mention default thresholds or result ordering, but defaults are visible in the schema and the core call pattern is clear.

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 only 57%, and the description adds no parameter-level guidance. It never mentions top, searchType, minImpressionsPerPage, or how filters and dates shape the analysis, leaving the agent to infer tuning from parameter names alone.

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 precise detection logic: queries for which two or more pages receive impressions, i.e. cannibalization. It uses a specific verb ('Finds') and a clear resource, and it sets the tool apart from generic analytics siblings by tying it to stuck rankings despite good content.

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 an explicit trigger: 'Run this when rankings look stuck despite good content.' This tells an agent when to select the tool, though it does not name alternatives or say when not to use it, so it stops short of a 5.

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

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

Annotations already declare the operation read-only, idempotent, and non-destructive, covering the safety profile. The description adds meaningful behavioral information by stating that rows carry deltas and that results are sorted by click change into winners and losers. There is no contradiction with the annotations.

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

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

The description is a single compact sentence that front-loads the core behavior and includes dimensions, delta output, and sort order. There is no filler, repetition of annotations, or unnecessary detail.

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 12-parameter tool with no output schema, the description, rich parameter schema, and strong annotations together provide a mostly complete picture. It explains the essential output semantics and the comparison nature, while the schema covers date syntax and the special date-dimension caveat. A short example or explicit note about output columns would make it fully complete, but the current definition is adequate.

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 high at 83%, so the schema already documents parameters like dimension, filters, date syntax, dataState, and aggregationType. The tool description mainly echoes the dimension enum and adds little new parameter-level meaning; it does not clarify top, rowLimit, searchType, or how filters interact with the comparison. 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 names a specific action (compare), the resource (current vs previous period), the available grouping dimensions (query, page, country, device, searchAppearance, date), and the output behavior (deltas sorted by click change into winners/losers). This is specific enough to distinguish it from single-period tools like gsc_search_analytics and from the GA-specific ga_compare_periods sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool: whenever a period-over-period comparison with winners/losers is needed. However, it does not explicitly state when to prefer this over related siblings such as gsc_search_analytics, gsc_opportunities, or ga_compare_periods, nor does it mention any exclusions or alternatives. The usage context is left mostly 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, openWorldHint, idempotentHint, and destructiveHint: false, so the safety profile is covered. The description adds valuable behavioral context by explaining the ranking logic (CTR far below typical for that position, weighted by impressions) and provides concrete benchmark CTR rates by position. It does not contradict annotations and gives more than the minimal safety disclosure, though it doesn't describe output format or pagination.

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

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

The description is four sentences with no fluff. It leads with a punchy summary ('Ranks well but is not clicked.'), then explains the logic, distinguishes the sibling tool, and provides benchmark data. Every sentence earns its place and the structure is front-loaded with the most critical information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 9 parameters and no output schema, the description covers the core concept, differentiation, and gives practical benchmark data. It does not explain how to combine parameters or what the output looks like, but the annotations cover safety, the schema describes dates and filters, and the description provides enough to make a correct call. Some gaps remain around searchType and dimension interactions, but overall it is fairly complete for an agent.

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 44%, meaning several parameters (top, dimension, searchType, maxPosition, minImpressions) lack descriptions in the schema. The description compensates partially by mentioning 'top positions' (relating to maxPosition) and 'weighted by impressions' (relating to minImpressions), but it does not explain filters, searchType, or dimension. Given the low coverage, the description should have provided more parameter-specific guidance, but it does add some conceptual meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: it identifies queries that rank well (in top positions) but have weak CTR, weighted by impressions. It distinguishes itself from the sibling gsc_opportunities by explicitly noting that tool is for queries not yet in the top 10. The verb 'identifies' is implied but the resource and scope are specific, making it distinct from other GSC tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly tells the agent when to use this tool vs. the alternative: 'Not yet in the top 10 is gsc_opportunities instead.' This provides a clear exclusion condition. It also implies usage is for queries already ranking in top positions, which is a clear context signal.

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 and non-idempotent behavior. The description adds that other owners retain access and that the removal is irreversible for this account until re-added and re-verified, which goes beyond the annotation flags and provides useful context.

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 concise sentences, both essential. The first states the core action and immediate consequence; the second delivers the irreversibility warning. No wasted words and information is front-loaded.

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 delete operation with annotations covering destructive behavior, the description covers the key behavioral aspects: account-level access loss, impact on other owners, and irreversibility. It is sufficiently complete given the tool's simplicity and the lack of an output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add any extra meaning about the parameters beyond what the schema already provides (e.g., the confirm constraint and siteUrl example are already documented).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action: removing a property from the authorized account, and specifies the consequence that the account loses access while other owners keep theirs. This is distinct from sibling tools like gsc_add_site or gsc_list_sites, and the title reinforces the purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use it (to remove a property) but does not explicitly contrast with alternatives like gsc_delete_sitemap or note conditions for use. The irreversibility warning serves as a caution, but there is no explicit 'when not to use' or comparison to related 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?

Even though destructiveHint=true and readOnlyHint=false are in annotations, the description adds valuable context: Googles stops reading it but the file is untouched. This shapes the agent's expectation of the side effect and distinguishes it from deleting the file itself, going beyond the annotation flags.

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 with no waste. The first sentence states the action and effect immediately; the second gives the necessary prerequisite. Perfectly front-loaded and scannable.

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 2-parameter tool with no output schema, the description covers everything needed for correct invocation: what it does, the side effect, and how to obtain the required parameter. The destructive annotation is further explained, and no critical details 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 50% (siteUrl is described with an example; feedpath has only format uri). The description tells the user to get the 'exact feedpath' from gsc_list_sitemaps, adding meaning to feedpath, but does not fully elaborate its nature. It partially compensates for the coverage gap, so 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 states a specific verb ('Remove') and resource ('sitemap from a Search Console property') and clarifies the effect ('Google stops reading it; the file itself is untouched'). It clearly differentiates from siblings like gsc_delete_site and gsc_submit_sitemap by focusing on sitemap removal only.

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 instructs to 'Use gsc_list_sitemaps first to get the exact feedpath', providing a clear prerequisite and pointing to the correct sibling tool. This gives the agent a step-by-step guidance and implies when not to call this tool (without checking the feedpath first).

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

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

Beyond the readOnly/idempotent annotations, the description discloses behavior that affects expectations: one quota call per URL, orphan=true semantics, and the caveat that orphan is only set on complete inspections because Google omits lists on partial results. This explains output nuances the annotations cannot 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?

The description is compact and front-loads the key batch/single-URL decision. Every sentence adds distinct information: scope, output fields, orphan behavior, and quota constraints. There is no filler or repetition of schema 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?

With no output schema, the description enumerates the returned data (verdict, coverage state, robots, last crawl, canonical mismatch, sitemaps, referring URLs, rich-result issues) and flags operational constraints. An agent can anticipate both the response shape and the invocation size before calling.

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 83%, so the schema already documents most parameters. The description adds context around 'first N sitemap URLs' and the batch-versus-single-URL distinction, but it does not add detail for languageCode or the precise filtering behavior of onlyProblems. This is adequate but not exceptional.

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 an explicit directive, 'Use this for a batch', identifies the resource as URL Inspection over a list of URLs or sitemap URLs, and enumerates the returned fields. It also distinguishes itself from the sibling gsc_inspect_url by stating that tool returns the full raw result for a single URL.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit when-to-use rule ('for a batch') and names the alternative for single URLs (gsc_inspect_url). The quota warning ('~2000/day per URL, keep batches small') provides practical invocation guidance that helps the agent choose appropriate batch sizes.

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 indicate readOnly, idempotent, and non-destructive behavior, so the description does not need to repeat that. It adds valuable behavioral context beyond annotations: the explicit quota (~2000 calls/day per property) and the breadth of checks performed (mobile usability, rich results, AMP). This helps an agent anticipate rate limits and understand the result scope without conflicting with any annotation.

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

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

The description is a single, well-structured sentence that front-loads the core action and then lists the specific checks in a compact list. The quota note is appended efficiently at the end. There is no redundancy or filler; every clause contributes meaningful information, making it appropriately concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with moderate complexity (multiple checks but no nested objects) and no output schema, the description covers the main outputs and the key constraint (quota). It does not mention return format, but that is often inferred from Search Console's inspection response. The description is sufficient for an agent to decide when to call it and what to expect, though a brief note on response structure could elevate completeness to 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?

The input schema already provides full descriptions for all three parameters, including the requirement that inspectionUrl must belong to the property. The description does not add additional parameter-level semantics beyond what schema states; it simply reiterates the general purpose. With 100% schema coverage, the baseline of 3 is appropriate, and the description does not compensate further.

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 ('Run the URL Inspection API for a page') and enumerates concrete outputs (index status, crawl time, canonical, robots, mobile, rich results, AMP). This clearly distinguishes it from sibling tools like gsc_index_coverage or gsc_rich_results_report, which operate at site level and cover different data. An agent can immediately identify what this tool does and what 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?

The description provides clear context of the tool's purpose by listing the exact checks performed, which implies when it should be used (e.g., when a single-page inspection is needed). However, it does not explicitly state when not to use it or name alternatives like gsc_index_coverage or gsc_site_snapshot. It offers no exclusions, only a clear scope, so it earns a 4 rather than 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, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it returns last submitted/downloaded times, errors, warnings, and URL counts, and explains the sitemapIndex behavior. However, it doesn't disclose details like pagination, response size, or what happens when no sitemaps exist, which would be useful for a listing 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?

Two sentences with zero waste. The main purpose is front-loaded, and the sitemapIndex behavior is explained in a single follow-up sentence. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only listing tool with 100% schema coverage and no output schema, the description is nearly complete. It explains the main use case, the sitemapIndex variant, and what data is returned. The only minor gap is that it doesn't mention what happens when no sitemaps are submitted or whether the response includes a list of sitemap types (e.g., sitemap vs index), but these are minor against the annotations and 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 both parameters well. The description adds a bit of value by explaining the purpose of sitemapIndex ('lists its child sitemaps instead of the submitted ones') and the use case for finding errors/warnings, but it doesn't add syntax or format details beyond the schema. 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 uses a specific verb ('List') and resource ('sitemaps submitted for a property'), and immediately distinguishes itself from sibling tools like gsc_submit_sitemap and gsc_delete_sitemap by focusing on listing. It also adds the sitemapIndex behavior, which differentiates it from a generic sitemap 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?

The description clearly states when to use the tool (list submitted sitemaps) and when to use the sitemapIndex parameter (to list child sitemaps inside an index file). It doesn't explicitly name alternatives or exclusions, but the context is clear enough for an agent to select it over siblings like gsc_submit_sitemap or sitemap_check.

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 tool is safe to call. The description adds 'authorized account' indicating an authentication requirement, and no side effects are implied. This is fully consistent with the annotations and provides additional context.

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

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

The description is a single, concise sentence with no redundant phrasing. It directly states the action, target, and scope, which is optimal for this simple tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description fully explains the tool's function and what the output will be (list of properties with permission levels). There is no output schema, but the description provides sufficient information for an agent to understand the result.

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

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

The tool has zero parameters, so the schema coverage is complete by definition. There is nothing further for the description to explain about inputs, and no ambiguity exists.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'List', the resource 'Search Console properties (sites)', and the scope 'authorized account can access' with 'permission level'. This distinguishes it from sibling tools like gsc_search_analytics or gsc_list_sitemaps, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implicitly indicates its use case (enumerating accessible properties) but does not explicitly name alternative tools or conditions for selection. It is clear enough for an agent to infer when to use it, but lacks the explicit contrast seen in the best examples.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint: false, covering the safety profile. The description adds valuable behavioral context beyond that: it explains the selection criteria (position 8-20, configurable), grouping by page, and the WordPress post ID mapping behavior when a site is configured. No contradictions with annotations.

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

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

The description is two sentences with no filler. The core concept—striking-distance keywords—is front-loaded, followed immediately by the key exclusion case. Every phrase contributes meaning, balancing clarity with brevity.

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 10 parameters and no output schema, the description conveys the essential selection logic and output shape (grouped by page, mapped to WordPress post IDs), and the schema covers parameter-level details like date ranges and siteUrl. It falls just short of full completeness because it doesn't explicitly describe the return item structure or how 'when a site is configured' is determined, but for invocation purposes it is largely sufficient.

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

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

Schema description coverage is only 50%, leaving parameters like top, searchType, maxPosition, minPosition, and minImpressions undocumented. The description loosely references 'position 8-20' and 'high impressions', which maps to those position/impression parameters, but it does not fully compensate for the undocumented ones, especially searchType and top. The schema-covered date/country/filter parameters don't need additional 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?

The title and description clearly define the tool's purpose: it finds striking-distance keywords—those ranking at positions 8-20 with high impressions—and groups them by page with WordPress post ID mapping. It also distinguishes itself from the sibling gsc_ctr_opportunities, making the tool's scope unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly defines when to use this tool (keywords not yet on page one but within striking distance) and when not to: 'Already in the top 10 but under-clicked is gsc_ctr_opportunities instead.' This directly routes the agent to the correct sibling based on ranking position.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds behavioral details about grouping by page and optional checks for headings/FAQ schema, which are not in annotations. It does not contradict annotations and adds meaningful context about what the tool does with the 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?

The description is a single, front-loaded sentence that immediately conveys the core purpose and differentiator. Every part adds value – examples of query types, grouping behavior, optional check, and target use case. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.