SearchLink

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description only needs to add context beyond that. It adds that data comes from the Bing AI Performance CSV uploaded in the dashboard, which is useful context for data freshness and source. However, it does not disclose pagination, rate limits, or behavior when no CSV data exists, so it provides modest additional transparency.

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 first sentence front-loads the core purpose, and the second adds a valuable data-source note. Every sentence earns its place, though the structure could be tightened with an explicit verb at the start.

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 one-parameter read-only tool, the description covers the output contents (frequency, pages, questions) and the data source, which gives an agent a reasonable idea of the result. However, there is no output schema and the description doesn't mention response format, empty-data behavior, or potential caveats, leaving some gaps for a complete call.

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

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

Schema description coverage is 100%, with the single `site` parameter fully documented including accepted formats and a hint to call list_sites if unsure. The description itself references 'this site' but does not add any new meaning beyond what the schema already provides, 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 identifies a specific resource ('this site'), a specific metric (how often Microsoft Copilot cited it in AI answers), and the data dimensions (frequency, pages, questions). This clearly differentiates it from siblings like bing_performance or search_performance, which cover broader areas. It lacks an explicit verb like 'get' or 'list,' but the phrasing clearly implies a read/report operation.

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 no guidance on when to use this tool instead of related siblings such as bing_performance or search_performance, and it names no alternatives or exclusions. The schema's 'Call list_sites if unsure' is only a fallback for site format validation, not a usage guideline for tool 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, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: repeated runs are required for trustworthy numbers because AI answers vary, results are retained for a week, Search Console data is never sent to the AI, and a plan tier is required. It does not discuss latency or cost of multiple runs.

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

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

The core action is front-loaded in the first sentence, followed by the rationale, constraints, and eligibility. Sentences are dense but each carries information (variance, retention, privacy, plan). Slightly long for a three-parameter tool, but nothing is filler.

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

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

With no output schema, the description carries the burden and does state the return shape in prose (citation frequency and the sites the AI cites instead). Combined with the retention window and plan gating, an agent has enough to call it correctly; only the ai_citations relationship and any latency expectations are unaddressed.

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 and the schema already documents site, questions, and runs with formats and limits. The description still adds meaning by explaining *why* runs matters (variance makes single runs untrustworthy) and why questions must be verbatim user phrasing rather than invented keywords.

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 concrete verb and resource: it asks Gemini with Google Search each user-written question repeatedly and reports citation/mention frequency plus competing cited sites. An agent can grasp exactly what the tool produces. It does not, however, distinguish itself from the close sibling ai_citations, which an agent might confuse it with.

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 use case ("do AI answers recommend me?" questions) plus prerequisites: questions must be in the user's own words, and "Starter plan and up" gates access. It stops short of naming alternatives or exclusions relative to ai_citations, so an agent gets context but no routing guidance between the two citation-oriented tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: the tool correlates rolling-out updates with traffic changes, which is not obvious from the schema alone.

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

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

Two short sentences with no filler. The core purpose is front-loaded, and the usage guidance earns its place by telling the agent when this tool matters.

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

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

For a simple read-only tool with two optional parameters and no output schema, this is reasonably complete. It communicates the data source, the relationship to traffic, and a likely use case, though it does not describe exact return formatting or pagination.

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

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

Schema description coverage is 100%, so the schema fully documents both parameters. The description adds a high-level frame ('ranking and spam updates' and 'while your traffic changed') but does not add parameter-level detail beyond what the schema already states.

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

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

The description clearly identifies the resource: Google's own list of ranking and spam updates, and it explains that the tool connects those updates to traffic changes. It is distinguishable from siblings like traffic_history or measure_change because it centers on Google's published updates rather than site metrics, though it lacks a direct imperative verb like '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?

It gives a concrete use case: check this before blaming your own edits for traffic changes. This is clear context for when the tool is appropriate, though it does not name alternatives or explicitly say 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 flag this as read-only and non-destructive; the description adds the connection prerequisite and clarifies the data scope, including ChatGPT and Copilot-powered search. It does not describe failure behavior when Bing is not connected, but with annotations covering the safety profile that is a minor gap.

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

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

Two compact sentences deliver the essential data categories and the prerequisite, with no filler or repetition of the schema. The most informative content 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 read-only reporting tool with two well-documented parameters, the description covers what data the agent will get and the connectivity precondition. It is complete enough to invoke correctly; the absence of an output schema is offset by the clearly implied payload of queries, pages, metrics, and crawl problems.

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 covers both parameters (site and limit) at 100% with detailed descriptions, so the description does not need to repeat them. The description adds no parameter-level meaning beyond what the schema already provides.

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

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

The description clearly identifies the resource (Bing performance) and the data returned: clicks/impressions, top queries/pages, and crawl problems, while adding useful context that Bing powers ChatGPT search and Copilot. It distinguishes from likely Google-focused siblings like search_performance through the explicit Bing framing, though it lacks a specific verb such as 'get' or '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 prerequisite 'Needs Bing connected in Settings' is explicit and gives actionable context for when the call can succeed. The data categories imply the tool is for Bing-specific SEO performance, but it does not name alternatives 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=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context about the split logic and brand-word configuration, but it does not disclose details such as the comparison period or data lag; those appear only in the schema. This is acceptable given the annotation coverage, though not especially rich.

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

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

Two concise sentences with no filler. The main purpose is front-loaded and the setup instruction ('Set your brand words in Settings') is included without redundancy. 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 read-only report tool with full schema coverage and safety annotations, the description provides the core purpose and the essential non-obvious setup step. The absence of an output schema means the description could do slightly more to describe return values, but the description's split definition and the schema's comparison details together give an agent sufficient context 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 schema fully documents all three parameters (days, site, terms) with meaningful descriptions. The tool description adds context around brand words and their relation to Settings, but this is marginal beyond what the schema already states. 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 identifies the tool's function: splitting searches into branded and non-branded segments, with a specific verb ('splits searches') and resource ('searches'). It conveys the purpose effectively but does not explicitly differentiate from sibling tools like search_performance or measure_change.

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 ('so growth is not hidden behind your own brand') and mentions configuration ('Set your brand words in Settings'), but it does not explicitly state when to use this instead of an alternative sibling tool or give exclusion criteria. Usage context is present but under-specified.

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 agent knows this is a safe read operation. The description adds the framing that these pages are 'usually the cheapest wins' but does not disclose additional behavioral details such as return format or pagination; this is acceptable given the annotations, though the description adds little beyond the tool's concept.

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 only two sentences and both are immediately understandable, with the core concept front-loaded. The second sentence is a useful strategic heuristic rather than 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 read-only list tool, the schema plus annotations cover parameter meaning and safety, leaving the description to explain what the tool surfaces—which it does. However, it does not mention output shape or period-comparison details beyond the schema, and there is no sibling routing, so the description is adequate but not fully complete.

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

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

The input schema provides descriptions for all three parameters (site, days, limit), so schema coverage is 100%. The description does not add parameter-level meaning beyond what the schema already conveys, apart from framing the output as 'fading' pages, which is implied by the tool name and title. 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 clearly identifies the resource ('pages that used to bring clicks and are fading') and the intended follow-up action ('refresh instead of writing something new'), so the purpose is understandable. However, it relies on a noun-phrase style and the title rather than an explicit verb like 'lists' or 'identifies', and it does not differentiate from sibling tools such as find_opportunities.

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

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

There is no explicit guidance on when to use content_decay versus alternatives like find_opportunities or indexing_gaps. The only advice is strategic ('cheapest wins: refresh instead of writing something new'), which tells the agent what to do with the results, not when this tool should be selected. No exclusions or alternative tool names are provided.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the agent knows this is a safe, read-only, open-world operation. The description adds context about the type of output (queries and pages) but does not disclose behaviors like rate limits, pagination, or how 'losing clicks' is precisely defined. It does not contradict 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, efficient list of three opportunity criteria. It is front-loaded with the core purpose and contains no filler or redundant phrases. Every element contributes meaning, making it highly concise and easy to parse.

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 diagnostic tool with three well-documented parameters and no output schema, the description gives a clear picture of what the tool finds. It does not describe the result format (e.g., a list of objects), but that is not essential for an agent to understand the purpose. The main gap is that it does not mention the time-comparison logic (already in the days parameter) or how 'losing clicks' is calculated, but these are partially covered by the parameter docs. Overall, the description 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?

The input schema has 100% description coverage for all three parameters (days, site, limit), so the baseline is 3. The tool description does not add any parameter-specific meaning; it does not explain how 'days' affects the comparison or how 'site' scopes the search. Since the schema already covers these, the description does not need to repeat them, but it also does not enhance understanding beyond what the schema provides.

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

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

The description precisely enumerates three concrete opportunity types: high-impression/low-click queries, queries ranking #8-20, and pages losing clicks. This clearly distinguishes it from sibling tools like content_decay or indexing_gaps, which target different specific patterns. The verb 'find' and the resource (opportunities) are implied by the name and context, and the description gives an 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?

No guidance is provided on when to use this tool versus alternatives. It does not mention any exclusions, prerequisites, or sibling tools. While the description explains what it does, it leaves the agent to infer when it should be chosen over other diagnosis tools (e.g., content_decay or keyword_clashes).

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

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

Annotations declare destructiveHint=true and openWorldHint=true, but the description adds substantial context beyond them: the old title is retained so undo_fix can restore it, the change is tracked for a 4-week follow-up email, and the call hits the user's own site via the WordPress REST API. These are real behavioral traits, not restated annotations.

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

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

Front-loaded with the action and the most important operational rule (preview-then-confirm) before moving to retention, tracking, and prerequisites. Slightly long and partly restates schema-level guidance (confirm behavior, title length), which costs it a point.

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

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

For a mutation tool with no output schema, the description covers the preview response ('show the current title and the proposed one'), the undo path, the verification loop, and the setup prerequisites. An agent has everything needed to call it correctly and safely.

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

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

Schema description coverage is 100% and all four parameters are documented in the schema, so the baseline is 3. The description reinforces the confirm semantics and new_title intent but adds no syntax, format, or constraint detail the schema does not already carry.

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 ('Changes the title of one post or page on the user's WordPress site') and frames the scope as a single page, which cleanly separates it from sibling audit tools like track_change or undo_fix. An agent can identify the action without opening the schema.

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

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

Gives an explicit two-step protocol: call first WITHOUT confirm to preview, then call again with confirm: true only after the user approves. It also states prerequisites (WordPress connected in SearchLink Settings, Starter plan and up), leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description does not add behavioral specifics like data latency, rate limits, or side effects, but it does hint at the output format (one line per site). Since annotations carry the main safety disclosure and the tool is read-only, the description meets the minimum bar without contradicting 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 short sentences with zero extraneous wording. It is front-loaded with the primary output ('One line per site: clicks change, the biggest problem, and what to do'), followed by a targeted use case. This is an efficient, well-structured description.

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 tool with one parameter and no output schema, the description provides sufficient information about what the agent can expect: a compact per-site summary with key metrics and recommendations. It does not explain how 'biggest problem' is determined, but that is not essential for calling the tool. The parameter's behavior is covered in the schema, making this reasonably complete.

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

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

The input schema fully documents the only parameter (days), including default, range, and comparison logic, so schema description coverage is 100%. The tool description does not mention the parameter at all, but since the schema is complete, the baseline of 3 applies. No additional semantic value is added by the 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's output: a one-line summary per site covering clicks change, biggest problem, and recommended action. It also frames the scope as 'all my sites' and highlights suitability for agencies with many sites, which distinguishes it from single-site tools like site_overview or page_check. However, it doesn't explicitly name sibling alternatives, so differentiation is implied rather than explicit.

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

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

The description provides a clear when-to-use condition: 'Good for agencies with many sites' suggests it is intended for multi-site overviews. It does not mention when not to use it or explicitly state alternatives, such as using a single-site tool for detailed analysis. This is adequate guidance but leaves comparison to the agent.

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

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

Annotations already establish read-only, non-destructive, open-world behavior. The description adds the comparison/inspection mechanism, but does not disclose rate limits, per-URL inspection overhead, or what happens after inspection. It provides some context beyond annotations but not rich behavioral detail.

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

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

Two short sentences contain the mechanism, the result, and the user value, with zero filler. The operational statement is front-loaded and the second sentence adds a memorable framing without 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 read-only tool with only two well-documented parameters and no output schema, the description covers the purpose, inputs, and likely output concept well. It is only missing an explicit statement of what the returned report contains, which would make it fully complete.

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

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

The input schema has 100% coverage and already documents site formats and the limit range with defaults. The description adds no parameter-specific meaning beyond restating the tool's purpose, so the schema bears the full burden and the baseline 3 applies.

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

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

The description names a specific verb and resource: it compares sitemap URLs with pages receiving impressions and inspects the worst offenders. This makes the tool's function concrete and separates it from general performance or search tools, while the title reinforces the gap concept.

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 the tool: any time you need to surface sitemap pages that get no Google impressions. It does not name sibling alternatives or exclusions, so it stops short of a 5, but the intended use case is explicit enough to guide 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the upstream API identity, which is genuine context, but omits known operational traits like URL Inspection API quota limits and the fact that site must be a Search Console property the caller can access.

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 statements with the outcome front-loaded ahead of the API citation. The developer-docs URL is slightly bulky but justifiable provenance for a Google-backed 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?

With no output schema, the description usefully enumerates what comes back (index status, crawl date, canonical, blocking issue), and the two required parameters are fully documented in the schema. Only the missing usage prerequisites keep it short of full marks.

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

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

Schema description coverage is 100% and the site parameter already documents accepted formats plus 'Call list_sites if unsure.' The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource with concrete return facts: whether the URL is indexed, crawl date, Google's chosen canonical, and blocking issues. An agent can distinguish this from siblings like page_check or indexing_gaps because the scope is a single URL's index status, not a page audit or a gap 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?

Usage is implied by the described outcome (checking a specific URL's index status), but the description never says when to prefer this over page_check or indexing_gaps, nor does it state prerequisites such as needing the site verified in Search Console. Minimum-viable routing guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds the account-tier limitation ('Pro and Agency') and the conceptual event of ranking swaps, which is useful. However, it doesn't disclose data recency, pagination, or output characteristics, which would add value beyond the annotations.

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

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

The description is two sentences and front-loads the core function in the first sentence. The phrase 'Pro and Agency.' is terse but informative about availability. It could be slightly more formal, but there is no fluff 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 3-parameter tool with no output schema, the description gives only a high-level idea of what is returned. It doesn't explain how to interpret the clash list or what actions to take from it. The schema covers input mechanics, and the account restriction is noted, but result interpretation and data freshness remain 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 100%, with detailed parameter descriptions for days (including data lag), site (format and scoping), and limit (bounds and default). The tool description adds no param-specific meaning beyond the general purpose, so it stays at the baseline set by the schema.

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

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

The description clearly states a diagnostic purpose: detecting cases where multiple of the user's own pages compete for the same search results ('Searches where several of your own pages show up, so Google keeps swapping them and none settles high'). This distinguishes it from broad performance or opportunity tools, though it doesn't explicitly name sibling alternatives or use formal terminology like 'keyword cannibalization'.

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

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

There is no guidance on when to use this tool instead of alternatives like find_opportunities, content_decay, or indexing_gaps. The only contextual hint is 'Pro and Agency', which is an account-tier restriction, not a usage condition. No typical scenarios, prerequisites, or exclusions are given.

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

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

Annotations already cover read-only safety (readOnlyHint=true, destructiveHint=false). The description adds useful behavioral context beyond that: the list is restricted to sites SearchLink can read on the user's plan, and it reveals the specific output dimensions (access level, plan limit, Bing connection). 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?

Three short sentences carry only essential information: what is listed, what to use it for, and its read-only nature. The purpose is front-loaded and every clause 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 zero-parameter, read-only list tool, the description fully equips an agent: it identifies the resource, the filtering condition (plan access), the returned fields, and when to call it. No output schema exists, but the enumeration of returned data compensates sufficiently.

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 has zero parameters and schema description coverage is 100%, so the schema imposes no burden. The description appropriately focuses on the output rather than parameters, matching the baseline for no-parameter tools.

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 ('Lists'), a clear resource ('sites in the user's Search Console that SearchLink can read on their plan'), and the key data included (access level, plan limit, Bing connection status). This clearly differentiates it from siblings like search_performance or sitemaps, which target different resources or metrics.

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 invocation condition: 'Call first when the user has not named a site.' This tells the agent when to use the tool, but it does not name alternative tools or explicitly state when not to use it, so it falls just short of the full 'when/when-not/alternatives' 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 cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint), but the description adds real behavioral context: the counterfactual design against the whole site to strip seasonality and Google updates, the plan requirement (Starter and up), and the underlying GSC Search Analytics API it reads. It doesn't discuss rate limits or latency, hence a 4 rather than 5.

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

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

Front-loaded with the core question and the comparison method, with the plan/read-only/API details trailing. Slightly redundant, since 'Did a change work?' repeats the title and opening line, and the raw API URL is verbose, but every sentence carries information.

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

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

No output schema exists, yet the description tells the agent what comes back (a before/after table and a plain verdict), plus the data source and plan gate. Combined with fully covered parameters, an agent has nearly everything needed; only edge-case behavior (e.g., insufficient data) is unaddressed.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema, and baseline is 3. The description contributes one extra insight — that specifying a url judges a single page against the whole site — but adds no format or unit detail beyond what the schema provides.

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

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

States a specific verb and resource — compares the weeks after a marked change with the same number of weeks before — and frames the whole tool as answering 'did my change work?'. An agent can distinguish this measurement tool from siblings like track_change (which marks the change) without opening the schema.

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

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

Gives clear context for when to use it (after a marked change, or any date) and notes that the change date can be omitted to fall back to the most recent marked change. It does not explicitly name an alternative tool or state exclusions, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely new operational context: it performs a plain HTTPS request to the page and its robots.txt, uses no third-party API, and is free on every plan. It does not mention rate limits or timeout/error behavior, which keeps it short of a 5.

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

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

Front-loaded with the action and scope, then the return shape, then routing, then behavioral notes. All sentences carry information, though the enumeration of inspected elements is dense enough that it could be trimmed slightly.

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

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

With no output schema, the description still describes the return ('what it found and the problems in order of importance'), covers the single required parameter, the usage boundary against a sibling, and the request mechanics. Nothing essential for correct invocation is missing.

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

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

Only one parameter and schema description coverage is 100%, so the schema already documents the url field with format and required-ness. The description's mention of 'public page' adds a mild constraint (no auth-gated/internal pages) but no format or syntax detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb (fetches/checks) and resource (one public page) and enumerates exactly what is inspected: title, meta description, canonical, noindex, robots.txt, H1s, word count, alt text and structured data. It also names the sibling inspect_url and the distinction between them, so an agent can route correctly without opening either schema.

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

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

Explicit when-to-use phrasing ('Use it for "what is wrong with this page?"') is paired with an explicit when-not and the alternative tool ('for whether Google indexed it, use inspect_url'). Nothing about tool selection 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=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing the data sources (real-user Chrome field data and a lab test) and the backing API (Google PageSpeed Insights), but says nothing about latency, rate limits, or caching behavior of an external API call.

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

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

Two tight sentences that front-load the core value (real-user speed plus lab fixes). The API reference URL is somewhat boilerplate but justified for a tool wrapping a third-party API. No redundant sentences.

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 partially compensates by naming the returned metrics (LCP, INP, CLS) and the 'top fixes' payload. It still doesn't convey the shape of the response (scores, opportunities, diagnostics) or run-time expectations for an external API, leaving a moderate gap.

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

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

Schema description coverage is 100%, and both parameters (url, device) are fully documented in the schema with format and default. The description adds no additional parameter meaning, so baseline 3 applies.

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

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

The description names a specific capability: real-user Chrome speed metrics (LCP, INP, CLS) plus a lab test with fixes. An agent can tell this is a page-performance measurement tool. However, it never distinguishes itself from plausible siblings like page_check or inspect_url, which also touch page-level diagnostics.

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

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

There is no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. The mention of 'real-user' vs 'lab test' implies usage context but leaves the agent to infer when this is the right choice among 22 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, openWorldHint, and destructiveHint=false, so the safety burden is low. The description adds that results can be grouped, filtered, and compared to the previous period, but does not disclose output shape, pagination/limits behavior, or data-lag nuances beyond what the input schema already documents.

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 compact sentences with no filler. It front-loads the core purpose and then enumerates the distinguishing capabilities in a scannable list. Every phrase 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?

The input schema is rich and fully descriptive, covering all 8 parameters, defaults, and constraints. The description covers the core operations well. The only notable gap is that there is no output schema and the description does not explicitly state the returned metric set, though the sort_by enum strongly implies clicks, impressions, CTR, and position.

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 carries the parameter documentation burden. The description's mention of grouping, filtering, and previous-period comparison maps to group_by, filter_page/filter_query, and compare_previous, but adds no semantics beyond the already-detailed schema.

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

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

The description states a specific verb/resource: a flexible Google Search Console query over performance data, and summarizes the grouping, filtering, and comparison capabilities. It is clearly distinct from obvious siblings like list_sites or bing_performance, though it does not explicitly name a sibling or differentiate itself from traffic_history/site_overview.

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

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

The description implies usage: use this when you need a customizable query with grouping, filters, or period comparison. However, there is no explicit when-to-use versus alternative tools guidance, no exclusions, and no reference to sibling tools like bing_performance or traffic_history for simpler or different 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 readOnlyHint, destructiveHint, and openWorldHint. The description adds value by enumerating the returned data fields (last read, errors, warnings, URL counts), giving the agent a concrete idea of what to expect. 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 a single, information-dense sentence that front-loads the core purpose and lists the key output fields. There is no unnecessary verbiage.

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 one parameter and no output schema, the description conveys the essential return information. It might benefit from specifying the response format or structure, but the current description is sufficient for an agent to understand the tool's purpose 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%, and the parameter 'site' is thoroughly described in the schema itself. The tool description adds no additional parameter-specific information beyond what the schema already provides, so a 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 clearly states the tool reports status of submitted sitemaps, including specific fields (last read, errors, warnings, URL counts). It is distinct from siblings like health_check_all or site_overview because it focuses solely on sitemap data.

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 the tool is for checking sitemap status but provides no explicit guidance on when to prefer it over related tools like health_check_all or site_overview. No alternatives or exclusions are mentioned.

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 and non-destructive behavior. The description adds meaningful context beyond that: it compares against the previous period, notes that totals match the Search Console UI, and caps recommendations at 3. It also labels the tool as 'Read-only' again, slightly duplicating the annotation but reinforcing the 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?

Two sentences with no filler: the purpose is front-loaded, the returned content is clearly listed, and the alternative routing is given. Every phrase 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 read-only tool with 2 well-documented parameters and no output schema, the description tells the agent what it returns, how it compares periods, and when to choose a different tool. Nothing essential for selecting and invoking it correctly is missing.

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

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

Schema description coverage is 100%, so both `site` and `days` are already fully documented in the input schema. The tool description adds no param-specific semantics, but it doesn't need to; the schema carries the burden and does so thoroughly.

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 clear directive ('Start here') and explicitly enumerates what is returned: clicks, impressions, CTR, average position, page gainers/losers, and recommendations. It distinguishes itself from the sibling search_performance, so an agent can tell which tool to use for an overview vs. a custom 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 states when to use this tool ('for any "how is my site doing" question') and names the alternative for other cases ('For custom breakdowns use search_performance'). This leaves no ambiguity about the tool's role among the many 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=false and destructiveHint=false, and the description adds meaningful context: it submits URLs, expends daily quota, and benefits ChatGPT/Copilot. No contradiction with annotations; the quota disclosure is extra behavioral detail beyond what structured fields 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?

Two sentences, front-loaded with the action and purpose, followed by the quota warning and usage condition. No superfluous words; every clause 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 tool with two fully documented parameters, annotations covering safety, and no output schema, the description is sufficient. It covers when to use, what it does, and a key constraint (quota). Minor omissions like post-submission behavior are not critical for correct invocation.

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

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

Schema description coverage is 100% for both parameters (site and urls), so the structured schema already documents their meaning. The description adds no additional parameter-level insight beyond what the schema states; it implicitly references quota usage but the schema already notes that each URL uses one unit. Baseline 3 applies since the schema carries the load.

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 ('submit new or updated URLs to Bing') and the resource (Bing), with a clear goal (crawled fast). It also distinguishes from sibling inspection/analysis tools by focusing on submission, and the condition 'Only call when the user asks to submit' reinforces a unique 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 explicitly states when to use it ('Only call when the user asks to submit') and gives a practical constraint ('Uses your daily Bing quota') implying scarce usage. It does not explicitly contrast with alternatives, but the condition and quota note provide sufficient context for an agent to decide 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 cover the safety profile (readOnlyHint=false, destructiveHint=false), and the description adds real context beyond them: it writes only to SearchLink and never to Google, requires Starter plan or above, and that results surface via the Monday email after about 4 weeks. Minor tension with openWorldHint=true versus 'no external API', but the notes go to a remote service, so this reads as additive rather than contradictory.

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 purpose and the trigger, but 'Writes only to SearchLink, never to Google' and 'Stores the note in SearchLink only; no external API' restate the same fact, adding redundancy across four sentences.

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

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

For a mutation with no output schema, the description explains write scope, plan gating, and the downstream consequence (measure_change judgment, Monday email). Complete enough to call correctly, though it does not describe failure behavior or what a successful note looks like.

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 site, what, date, and url precisely. The description only gestures at 'its date and optional page', which the schema states more clearly. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('saves a note of something the user changed') with concrete examples (new title, rewritten page, redesign, migration). It also names the sibling that consumes the data (measure_change), letting an agent distinguish this from measure_change without opening either schema.

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

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

'Offer it whenever the user mentions a change' is an explicit positive trigger, and the mention of measure_change implies the downstream pairing. It lacks an explicit when-not-to-use or exclusion, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds useful behavioral context: data comes from 'our own archive' and persists beyond Google's window, plus the plan restriction. It does not describe output format, pagination, or update latency, but given the strong annotation coverage this is adequate.

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

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

Two short sentences deliver the core purpose, the key differentiator, and the access restriction with no filler. The most important information is front-loaded and every clause 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, two-parameter tool with fully documented parameters, the description is largely complete. It explains the data source, the time-window advantage, and the plan requirement. The lack of an output schema is partially mitigated by the phrase 'Traffic by month,' though a precise metric definition would make it fully complete.

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

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

Schema description coverage is 100%, with both 'site' and 'months' already well documented, so the baseline is 3. The description adds no parameter-specific meaning beyond the schema; 'by month' aligns with the months parameter but provides no extra detail.

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

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

The description states a specific resource and action: 'Traffic by month from our own archive.' It also differentiates itself from Google-window-limited tools by noting it 'keeps going after Google's 16-month window closes,' which helps distinguish it from sibling traffic/performance tools. However, it does not explicitly name a sibling or clarify which traffic metric is returned, so it stops short of a 5.

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

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

The description provides clear context for when this tool is valuable: when traffic history beyond Google's 16-month window is needed. It also notes the Pro and Agency plan restriction. It does not explicitly state when not to use it or name an alternative, so it lacks an explicit exclusion.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description adds real context: it only undoes the single most recent change, requires a paid plan, and operates via the WordPress REST API on the user's site. It still doesn't say whether the undo itself can be re-reversed or what happens when no change exists to undo.

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

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

Three short sentences, front-loaded with the core behavior, then the trigger, plan gate, and implementation note. The developer-docs URL is marginal but not wasteful.

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

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

For a 2-parameter mutation with no output schema and destructiveHint already declared, the description covers purpose, trigger, scope limitation, and entitlement. Missing only failure/return behavior (e.g. what it returns or errors when there is nothing to undo).

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 reinforces the 'most recent change' semantics for url and the site-scoping behavior, but adds no format or syntax detail beyond what the schema descriptions already state.

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

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

States a specific action ('puts back what a fix_title change replaced') tied to a named sibling tool, plus the exact scope ('most recent change on a page, or most recent change overall'). An agent can distinguish this from fix_title, measure_change, and track_change without opening any schema.

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

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

Explicit trigger ('use when the user asks to revert') and a prerequisite ('Starter plan and up'). It does not spell out when NOT to use it (e.g. undoing older/non-most-recent changes is impossible), which is a notable omission for a revert tool.

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