SEO Skill

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds meaningful behavioral scope by enumerating exactly what the comparison returns (totals, devices, moved pages/queries, matching-property GA sessions, in-window Google updates), which 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?

Front-loaded with the core operation, and the follow-up sentence handles the optional parameter. The first sentence is dense with comma-separated output clauses but each clause carries information, so there is no obvious waste.

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 appropriately shoulders the burden by describing the return contents, and it covers all three parameters plus the triggering context. It omits pagination/format details but nothing critical for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by clarifying 'pages' semantics for filtering ('narrows it to URLs that contain that text, such as /blog/'), which adds interpretation value on top of the schema's 'Optional URL text' wording.

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

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

States a specific verb and resource: it 'compares equal periods before and after a date' and enumerates the outputs (totals, devices, moved pages/queries, GA sessions, Google updates). The comparison operation is distinctive, but no sibling (e.g., seo_data or seo_report) is named, so the 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?

Gives concrete triggering contexts ('a site change or a Google update'), which tells the agent when this tool is the right choice. It stops short of naming an alternative tool or stating when not to use it, so it does not reach the 5 level.

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

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

Annotations only say readOnlyHint and openWorldHint, so the description carries the real burden and does well: it discloses the Clicky 31-day window, that Bing rolls up by week, that search_console rows include previous-period comparison, and that GA uses its own metric names rather than the tool's. It does not mention rate limits, quota, or upstream API failure behavior, which keeps it from a 5.

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

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

It is one paragraph, front-loaded with the differentiator before the per-source detail, and each source sentence adds distinct information rather than restating the schema. It is dense and could be split into bullets, but no sentence is filler.

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

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

For a nine-parameter, four-source read tool with no output schema and thin annotations, the description covers the essentials an agent needs: which source yields what, source-specific constraints (Clicky's 31-day cap, Bing's weekly grain and single dimension), and what a search_console row contains. Remaining mechanics (paging, detail levels) are fully documented in the schema.

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

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

Schema coverage is already 89%, so the baseline is 3, and the description earns above that by clarifying matching semantics ('page and query narrow to rows whose URL or query contains that text' – substring, not exact), that Bing only consumes the first dimension, and that Clicky's site may be a domain or site ID. The 'detail' enum's summary/rows/full progression and offset paging are left to the schema.

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

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

The opening line ('Raw rows for questions the report does not answer') frames it as the raw-data counterpart to the report, and each subsequent sentence specifies exactly what rows come back per source (search console dimensions, GA landing pages, Bing query/page by week, Clicky visits). An agent can distinguish it from seo_report, though the other siblings (seo_page, seo_research, seo_sites) are never named as alternatives.

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

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

The phrase 'for questions the report does not answer' gives an explicit selection rule against the report tool, and the per-source clauses imply when each source applies. However, there is no guidance on when to prefer seo_page or seo_research, and no statement of what this tool cannot do.

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

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

Annotations only cover readOnly and openWorld, so the description carries the rest and does deliver: it discloses a live check per URL (a costly, outbound operation), a 100-URL cap, sampling depth of top 20 live checks and top 10 for index status, and the 3-click/20%-retention threshold. It omits expected latency or failure behavior for the live checks, which keeps it off 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?

Every sentence carries content, but the structure is weak: an awkward fragment ('100 known URLs a run in a fixed order'), then a second feature tacked on with a bare 'Also:', and the baseline instruction buried mid-paragraph. The two distinct outputs should be split, and the primary action 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 must explain returns and does – labels (fix/check/expected/indexed), sort order, and the lost-click cohort definition. Only the paging contract of detail/offset is left entirely to the schema, which is acceptable given 100% parameter coverage.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning on top by tying the 28-day windows to start_date/end_date semantics and by advising the agent to keep the 'full' result for later comparison, which gives the detail parameter operational intent.

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

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

The description names a specific resource domain – Google indexing reasons for up to 100 known URLs plus lost-click pages – with enough detail (fixed ordering, labelling, sorting) that an agent can tell what it returns. It never names a verb like 'fetch' or 'list' and never references any sibling tool, so differentiation comes only from the domain wording.

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

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

It gives explicit timing guidance: use for a first baseline and then weekly, keep the full result, and compare by URL and reason to detect new reasons. That is concrete usage context, but no sibling alternative (e.g. seo_compare or seo_report) is named for related tasks.

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 readOnlyHint/openWorldHint, it discloses what findings look like (line, the words, a concrete fix, a category), how review items differ from errors and warnings, and that no accounts are read. It also flags an environment constraint the annotations do not carry: url fetching works only in CLI and local MCP.

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

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

The purpose is front-loaded and every clause carries content, but the opening sentence is a long, heavily parenthesized enumeration that takes effort to parse. The trailing 'It reads no accounts' is terse but useful; overall dense rather than 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?

With nine parameters and no output schema, the description compensates by explaining the shape of results (per-finding line, quoted words, fix, category) and the review-item distinction. It also covers the environment restriction on url and the default-preset behavior, which is everything an agent needs to call it correctly.

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

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

Schema description coverage is 100%, so every parameter is already documented, and the description mostly restates those semantics (the 'only ["ai"]' example, the url/CLI caveat). It adds little syntax or format detail the schema does not already supply, so the baseline of 3 applies.

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

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

The description names a specific verb and resource ('Checks landing page copy, blog posts, titles and meta descriptions') and enumerates the three finding families (AI patterns, weak copy, SEO rules). An agent can tell instantly this is a copy-linting tool, distinct from siblings like seo_page (extraction) or seo_compare.

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 operational context: use 'only' to skip a category such as house-style dashes, use 'url' instead of 'text' for a live page, and treat review items as judgement calls to read and apply only when they fail the stated question. It stops short of explicitly naming an alternative sibling (e.g. seo_page for extraction), so the when-not guidance is implied rather than complete.

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

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

Annotations already declare this as a read-only, open-world operation. The description adds useful provenance and freshness context by naming 'live page facts', Google’s index status from URL Inspection, and previous-period comparison, but it does not disclose auth requirements, rate limits, or how the sources are combined.

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 establishes the scope and then lists the three returned datasets. It is dense but every clause contributes directly to understanding the 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?

For a five-parameter aggregation tool without an output schema, the description sufficiently enumerates the data domains the agent will receive. It could say more about how the period and detail modes interact, but the schema covers those mechanics.

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 80%, so the schema already documents url, detail, offset, start_date, and end_date. The description does not add format or selection guidance beyond what the schema provides, so the baseline score 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 resource scope (one URL) and enumerates the three data domains returned: live page facts, Google index status, and Search Console queries. It is specific about contents, but it does not explicitly distinguish this aggregate view from siblings such as seo_index or seo_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 phrase 'Everything for one URL' implies this is the single-URL deep-dive tool, but there is no explicit guidance on when to choose it over seo_index, seo_data, or seo_compare. Usage is inferable but not directed.

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

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

Annotations only say readOnlyHint and openWorldHint, and the description adds substantial behavior beyond that: page sections check their top 20 URLs live, asking for issues re-runs the striking-distance/low-ctr/quick-wins checks, and several sections are explicitly labeled heuristics (ai-queries, traffic-drop, google-updates "timing only, not cause"). One gap keeps it from higher: the mark path "records what the person decided" and the hosted server "keeps the list between sessions," which is persistent state mutation under a readOnlyHint=true annotation — the description should reconcile that rather than leave the agent to notice it.

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

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

The bulleted section list is well structured and each section line carries real information. The opening is the problem: a single dense sentence packs all three calling modes, the beta behavior, and the fallback site-list case into one unbroken clause, making the most important routing rule the hardest part to parse. It is long but not padded — the cost is legibility, not 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 10-parameter, zero-required, multi-mode tool with no output schema, the description does the heavy lifting on return content, describing what each section yields (row counts and top rows, per-page share, comparison windows, 28/56-day before-and-after windows). Remaining gaps are date-range scoping across sections and pagination, both delegated to schema descriptions.

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

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

Schema description coverage is 100%, so the baseline is 3; the description earns above that by giving meaning the enum values cannot — what each of the twelve sections actually computes, when mark/issues replaces section, what saved contains and why it exists, and what end_date does to google-updates. It does not clarify how start_date/end_date interact with individual sections, which is left implicit.

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 is unusually specific about the verb and resource: it enumerates three calling modes (no site = cross-site weekly audit summary, site = main property report, site+section = one section's rows) and defines all twelve sections by what each computes. An agent knows exactly what the tool returns in each mode. It loses a point only because it never distinguishes itself from the six sibling tools (seo_data, seo_page, seo_index, seo_lint, seo_research, seo_compare), several of which plainly overlap on sections like google-updates and issues.

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?

"Start here" establishes entry-point ordering, and the description gives explicit sequencing rules: run without site first, then with site, then request one section; add mark and issues instead of section to record decisions; end_date selects an earlier google-updates entry. The gate that issues only persists for audited sites and otherwise returns JSON for the agent to save is spelled out. What is missing is when NOT to use this tool and which sibling to reach for instead.

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 readOnlyHint and openWorldHint annotations, the description discloses that calls consume the user's paid provider credits, explains provider key fallback behavior, details the ai_answers queue and paid-task retry mechanism, and gives a concrete cost estimate with an instruction to warn the user. These are exactly the behavioral traits 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 a single very long, dense paragraph that buries the action-by-action semantics in run-on prose. Most sentences carry useful information, but structure and scannability suffer, and the opening cost/account context precedes the core purpose.

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

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

For a 13-parameter, multi-action tool with no output schema, the description covers every action, the cost model, provider behavior, async queue handling, and how rows and citations are returned. An agent has enough information to select an action 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?

Although schema coverage is already 85%, the description adds substantial meaning beyond field-level definitions: target shape controls scope, scope overrides target shape, keywords vary by action with different limits, competitors applies only to link_gap, and tasks/also/brand apply only to ai_answers. It also explains how depth and per-action row outputs behave.

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 (DataForSEO/Ahrefs SEO data) and enumerates the actions it can perform with clear per-action scope. It does not distinguish itself from sibling tools such as seo_compare or seo_report, but the purpose is otherwise 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?

Usage is explained action by action: target shape determines domain, prefix or exact scope; provider defaults are described; keyword counts and limits are given for each action. It lacks explicit routing versus sibling tools like seo_compare, but within the tool the when-to-use guidance is strong.

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

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

Annotations declare readOnlyHint=true, but the description states that passing `add` starts a recurring weekly audit on a hosted server and can return a Stripe Checkout link that, once paid, activates a paid subscription. That is a state-changing, monetized side effect, directly contradicting the read-only annotation. An agent trusting only the annotation would believe the tool is a pure read when one optional parameter turns it into a billing-triggering mutation.

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 listing behaviour and the 'call it first' directive are front-loaded, and the detail about what the weekly audit includes earns its place by letting the agent explain the offer to a user. The parenthetical feature list is dense and runs long, but nothing is truly redundant.

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

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

With no output schema, the description does the work of describing the return payload: properties, per-site Bing site, research-key status, and a Checkout URL in the paid case. It stops short of covering edge cases such as calling `add` for a site already under audit or accounts with no readable properties.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: `add` triggers a weekly crawl, daily Google index checks, a Monday email/webhook, index-drop alerts, and possibly a payment flow. It also documents the cost gate, which the schema hints at but the description makes explicit.

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 set: it lists Search Console and Google Analytics properties, the matching Bing Webmaster site, and which research keys are set. That is clearly distinct from siblings like seo_data or seo_index, though none are named. The 'with add:' clause introduces a second, quite different mode (starting a paid audit), which slightly blurs what the tool fundamentally is.

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

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

'Call it first' gives unambiguous ordering guidance relative to the other seo_* tools, and 'Only when the person asks for it: a site can cost money' is an explicit precondition for the add path. What is missing is any named alternative for when the agent doesn't need the site list, or guidance on re-calling it after an audit is started.

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