Pylon SEO

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

Annotations cover the safety profile (not read-only, not idempotent, not destructive), and the description adds genuinely new context beyond them: the discovery scan is enqueued asynchronously, so the agent knows results are not immediate. It does not state what happens on a duplicate domain, which matters for a non-idempotent write.

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

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

Two short sentences, zero filler, with the action and the input-format constraint front-loaded and the async caveat last. 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 three-parameter write with no output schema and annotations already declaring the safety profile, the key operational fact (asynchronous discovery scan) is disclosed. The remaining gap is duplicate/already-tracked behavior for a non-idempotent tool, which the description leaves silent.

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 three parameters (label, domain, site_id) are already documented in the schema. The description only restates the bare-domain format, adding no syntax or format detail beyond what the schema provides — baseline 3.

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 ('Track a new competitor for a site') and constrains the input ('by its bare domain (no protocol)'). It is distinguishable from siblings like add_keyword and add_rank_alert by the resource name, though it never explicitly contrasts itself with them.

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

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

The intent (adding a competitor to a site) implies when to use it, but there is no explicit when-to-use, no prerequisites, and no mention of alternatives such as get_competitors or get_market_analysis. Usage is inferable rather than stated.

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, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds one genuine behavioral fact not in the annotations: intent is estimated when omitted. It does not disclose what happens on a duplicate keyword, whether this triggers ranking/scan work, or any quota limits, so it adds some but not rich context.

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

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

Two sentences, front-loaded with the purpose, then the parameter contract. No filler, no restatement of the tool name or title, and the most decision-relevant fact (required vs optional fields) is stated compactly.

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 four-parameter add tool with no output schema and annotations already covering the safety profile, the description covers the essentials: required fields, the intent enum, and the omission behavior. It is only short on edge cases such as duplicate keywords, limits, and downstream effects, which keeps it from a 5.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value: it supplies the four intent enum values (informational|commercial|transactional|navigational) that the schema lacks entirely (schema only says 'Optional intent'), and it states the estimation fallback when intent is omitted. The required/optional split merely restates the schema.

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

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

The description states a specific verb and resource: 'Track a new keyword for a site.' This is unambiguous and distinct from the read-oriented siblings (get_keyword_rankings, get_keyword_gaps) and from other add_* tools by resource. It does not explicitly contrast itself with siblings, but the verb+resource is clear enough that an agent can route correctly.

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

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

There is no when-to-use guidance, no prerequisites (e.g., the site must already exist / site_id must be valid), and no mention of alternatives such as importing keywords in bulk or the related add_rank_alert. The agent is told what the tool does but not when it is the right choice over 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, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context by defining the alert trigger semantics — a drop of N positions between ranking runs — which is not derivable from the annotations. It omits whether duplicate rules are rejected or what the creation response contains, keeping 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?

Two sentences, no filler, with the core action front-loaded before the trigger rule. Every clause carries information an agent needs.

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

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

For a simple two-required-parameter creation tool with no output schema, the definition covers purpose and trigger behavior adequately. Minor gaps remain around idempotency behavior on repeated calls and any required permissions, but nothing essential to 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 parameters are already documented in the schema; baseline is 3. The description restates that drop_threshold is a positive int measuring positions dropped between runs, which reinforces but does not extend the schema's '1-100' range note.

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: 'Configure a rank-drop alert rule for a site.' An agent can immediately tell this creates a rank alert, distinct from the read-side sibling get_rank_alerts. It stops short of explicitly naming that sibling as the read counterpart, so it is clear but not fully sibling-differentiated.

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 firing condition ('fires when any tracked keyword drops that many positions between runs') implies when the tool is relevant, but there is no explicit when-to-use/when-not guidance and no mention of alternatives such as get_rank_alerts or how this differs from adding other rules. Usage is inferable rather than stated.

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 read-only, idempotent, non-destructive, and closed-world, so the safety profile needs no restating. The description adds the payload shape (coverage %, delta vs previous run, intent buckets, keyword states) but no behavioral context such as freshness, time window, or what 'previous run' means.

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

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

A single tight sentence that front-loads the resource and then lists return dimensions with no filler. Efficient, though the dense parenthetical list is slightly harder to parse than separate clauses.

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 one-parameter read tool with strong annotations but no output schema, the description usefully compensates by enumerating the returns rather than leaving them opaque. The main gap is the unresolved overlap with get_ai_visibility.

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?

One parameter with 100% schema description coverage ('UUID of the site'), so the schema fully documents it. The description adds nothing about site_id scope or format, which is the expected baseline when the schema does the work.

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

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

States a specific verb and resource ('Google AI Overview coverage for a site') and enumerates the returned dimensions. Clear enough to act on, but it never distinguishes itself from the sibling 'get_ai_visibility', which sounds adjacent and could confuse selection.

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

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

No when-to-use, when-not-to-use, or alternative is offered. With 'get_ai_visibility' in the sibling list, the reader must guess which endpoint answers their question; the description provides no routing help.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful content context by naming what is returned (mention rate, engine sets), but does not disclose time range, caching, or other behavioral traits.

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 efficiently conveys purpose and content without filler. It is slightly list-heavy but appropriately sized for a simple read 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 one-parameter, read-only tool with no output schema, the description explains the returned subject matter (mention rate, engines) well enough to guide invocation. It omits some useful context such as the measurement period or output shape, but is largely 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?

There is one parameter with 100% schema description coverage ('UUID of the site'), so the schema already carries its meaning. The description does not add syntax or format detail beyond that, making the baseline 3 appropriate.

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

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

The description states a clear resource and content: an AI visibility overview measuring mention rate across named AI engines, plus current and planned engine sets. It is specific enough for an agent to know what data it retrieves, though it does not explicitly differentiate itself from the sibling get_ai_overview_presence.

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

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

The description gives no when-to-use guidance, no prerequisites, and does not mention any alternative or exclusion. An agent can infer it is for a site from the name, but there is no routing help against siblings such as get_ai_overview_presence.

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/idempotent/non-destructive, so the safety profile is covered. The description adds useful behavioral detail beyond them: results come from the latest run only, results are 'top' issues (ranked/capped), and the default page size is 25 with a hard cap of 200.

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, no filler, front-loaded with the resource and scope before the optional filter and return cap. Every sentence earns its place.

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

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

There is no output schema, so the description carries the return-value burden; it does state that up to `limit` instances are returned, which is adequate. It stops short of indicating what an 'issue' record contains (fields, severity distribution), leaving a minor gap for a tool with no output schema.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description adds genuinely new information not present in the schema: the default limit of 25 (the schema only states the 1-200 range) and the allowed severity vocabulary context.

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 ('get ... issues from the latest audit run for a site') and pins the scope to the most recent run. It does not explicitly differentiate itself from the sibling get_site_audit, which an agent could easily 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?

Usage is only implied: the description mentions an optional severity filter, from which an agent can infer when to narrow results, but there is no explicit when-to-use statement, no prerequisites, and no guidance on choosing between this and get_site_audit or get_site_changes.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds the notable fact that the authority score is Pylon-computed on a 0-100 scale, which clarifies the returned metric's origin. It still omits result count, ordering, and whether the list is paginated, which matters for a 'top N' style endpoint.

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

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

A single front-loaded sentence with no filler; the resource is stated before the qualifier. Minor jargon ('Pylon-computed') is the only cost.

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

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

For a simple read-only list tool with a fully documented single parameter, the description is adequate but leaves the return shape ambiguous — 'Top' implies a limit and ranking that are never quantified, and no output schema exists to resolve it.

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

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

Only one parameter, and schema description coverage is 100% ('UUID of the site'), so the schema carries the semantics fully. The description adds nothing about the parameter, which is acceptable at this coverage level.

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

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

Names a specific resource (referring domains) and scope (top, for a site), plus the authority metric returned. It is clear what the tool fetches, though it does not distinguish itself from any sibling because no other backlink-domain tool exists in the set.

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

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

There is no when-to-use guidance, no prerequisites (e.g., that a prior scan or crawl must exist), and no alternatives named. The agent must infer usage entirely from the name and the required site_id.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is fully covered. The description adds a useful behavioral note ('organic; Bing has no Copilot API split'), clarifying data scope, but discloses nothing about return shape, pagination, or rate limits.

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

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

A single dense sentence with the resource, scope caveat, and dimension semantics front-loaded; no filler or redundancy.

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

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

With no output schema, the description says nothing about what metrics are returned or their shape, and it omits any note on data range or sorting. Adequate to invoke, but incomplete for a metrics-retrieval tool.

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

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

Schema coverage is 67%; site_id and limit are documented in the schema. The description goes beyond the enum by spelling out the allowed dimension values and stating the default ('default query'), which the schema's bare enum does not convey.

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: 'Bing Webmaster Tools metrics for a site.' The parenthetical clarifies the organic scope and rules out a Copilot split, which helps distinguish it from AI-visibility siblings, though it never names get_gsc_metrics as the counterpart.

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

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

There is no explicit when-to-use guidance or mention of alternatives. An agent must infer from the name that this is the Bing counterpart to get_gsc_metrics; the description never states when to choose Bing metrics over GSC or AI-visibility 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, idempotentHint and destructiveHint=false, so the safety profile is covered structurally. The description adds useful content-level context by naming the snapshot metrics (DA, visibility, organic keywords, traffic, backlinks), but says nothing about ordering, limits, or behavior for a site with no tracked competitors.

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

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

A single, front-loaded sentence with no filler; the parenthetical field list is the most valuable part since there is no output schema. Slightly dense and could be split, but nothing is wasted.

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

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

With no output schema, the description compensates by naming the returned fields, and the single input parameter is documented in the schema. It lacks minor details (result ordering, empty-state behavior, count limits) but is sufficient 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?

Only one parameter (site_id) and schema description coverage is 100% ('UUID of the site'), so the schema fully carries the parameter semantics. The description adds nothing beyond what the schema provides — the correct baseline here is 3.

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 ('Tracked competitors for a site') and enumerates the snapshot fields returned, which is clear enough to distinguish it from the sibling add_competitor (a mutation). It stops short of an explicit verb like 'List/Retrieve', but the intent is 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?

There is no when-to-use guidance, no mention of prerequisites (e.g. that competitors must first be added via add_competitor), and no alternatives named. The word 'Tracked' hints at scoping to already-added competitors, but the agent must infer this.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds one genuine behavioral trait beyond annotations: the data is cached, so results may be stale or absent. It stops short of saying what happens on a cache miss (error vs. empty).

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

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

A single front-loaded sentence with no filler; the key qualifier ('Cached') leads. The parenthetical about the on-page grader is mildly redundant but still informative about provenance.

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 characterize the return value, and 'content-grade summary' remains vague about what fields or score shape come back. Combined with no cache-miss behavior, it is adequate but not complete enough for a tool whose result structure is entirely undocumented.

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 parameters documented ('Exact URL to look up', 'UUID of the site'), so the schema does the heavy lifting. The description's phrase 'for a URL on a site' merely restates the same two inputs without adding format, matching, or normalization guidance.

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 (a content-grade summary) and its scope (a URL on a given site), plus the origin ('from the on-page grader'). An agent can tell it returns a grading result rather than raw content or audit issues. It does not explicitly contrast with siblings like get_site_audit or get_cwv, 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?

'Cached' weakly implies this reads a previously computed grade rather than triggering a new one, which is useful context. However, there is no explicit when-to-use, no prerequisites (must a scan have run first?), and no named alternative such as start_scan or get_site_audit.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuine context beyond that by revealing the data comes from PageSpeed Insights as point-in-time snapshots across two device categories, but it says nothing about latency, rate limits, or freshness.

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

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

A single dense sentence that front-loads the resource and metric list before the source and scope. No filler, no 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 one-parameter read tool with no output schema, the description usefully enumerates the returned metrics (LCP, CLS, INP, FCP, TTFB) and the two device scopes, so the agent knows what comes back. Only minor gaps remain around freshness and any precondition for the site_id.

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

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

There is a single parameter with 100% schema description coverage, so the schema already documents site_id fully. The description adds no format, identifier, or validation detail beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description names the specific resource (Core Web Vitals, enumerated as LCP, CLS, INP, FCP, TTFB), the data source (PageSpeed Insights), and the scope (mobile + desktop snapshots). This clearly separates it from metric siblings like get_gsc_metrics or get_bing_metrics, though it never names an alternative explicitly.

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

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

There is no when-to-use or when-not guidance and no mention of prerequisites (e.g., whether the site must be scanned first) or alternatives. The agent must infer usage purely from the tool name and metric list.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is fully covered. The description adds the default values for surface and dimension, which is helpful context, but says nothing about data freshness, return shape, or rate limits – acceptable given the annotations carry the important behavioral burden.

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

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

Two tight sentences, front-loaded with the resource and followed by the parameter guidance that the schema lacks. Backtick formatting is efficient; nothing is wasted, though the parameter clause reads a little like raw schema output.

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 should say what a 'metric' row contains (clicks, impressions, CTR, position) and what a dimension grouping returns; it does not. It also omits the prerequisite that site_id must reference a connected GSC property, leaving a real gap for a 4-parameter analytical tool.

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

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

Schema coverage is only 50% (limit and site_id documented; the two enum params are not), and the description fills exactly that gap by listing allowed values and defaults for surface and dimension. This meaningfully compensates for the schema shortfall rather than repeating it.

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

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

States the specific resource (Google Search Console metrics) and scope (for a site), which distinguishes it from get_bing_metrics and the AI-visibility siblings. It stops short of explicitly naming the sibling it replaces, so the differentiation relies on the reader knowing 'GSC' means Google.

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 choose this over get_bing_metrics, get_ai_visibility, or get_keyword_rankings, nor any prerequisite (site must be a connected Search Console property). The parameter defaults imply what can be requested but give no usage context or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the ordering rule (by opportunity score), which is useful, but it omits how many competitors are compared, whether results are capped or paginated, and what the 'opportunity score' is derived from.

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

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

A single compact sentence with the definition front-loaded and the ordering rule appended. Nothing is wasted, though the parenthetical construction makes the ordering rule slightly buried.

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

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

With no output schema, the description should carry more of the return-value burden — e.g. that each gap includes the keyword, the ranking competitor, and the score. Annotations cover the safety profile, but the agent still cannot predict the shape or size of the result set.

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

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

There is a single parameter (site_id) with 100% schema description coverage, so the schema fully documents the input and the description adds nothing parameter-level. The counterintuitive absence of a competitor parameter is not explained, which is the one place the description could have added value.

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

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

The description gives a specific resource (keyword gaps) and defines the concept precisely — keywords a competitor ranks for that the site does not — which an agent can distinguish from get_keyword_rankings or get_market_analysis. It stops short of naming sibling alternatives or scoping which competitors are compared, so it is clear but not fully differentiated.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternative tools such as get_market_analysis or get_competitors that also surface competitive keyword data. Usage can only be inferred from the name and the parenthetical gloss.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered by structured data. The description adds useful return-shape context (position deltas, URL, country, device) but says nothing about scoping limits, pagination, or row caps for a read tool. Adequate but not 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?

A single compact sentence that front-loads the core purpose and tucks the return fields into a parenthetical. Zero filler and nothing to trim.

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 takes on part of the return-documentation burden and does so by enumerating the key returned fields. For a one-parameter read tool whose annotations cover safety, this is nearly complete; only sorting, scope limits, and volume 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?

Only one parameter (site_id) and schema coverage is 100%, so the schema fully documents it. The description adds no additional meaning about the parameter (e.g., format or where to obtain the UUID). Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description names a specific verb+resource ('Tracked keyword positions') and enumerates the returned fields (current + previous position, URL, country, device), so the agent knows exactly what data comes back. It does not, however, explicitly contrast itself with close siblings such as get_keyword_gaps, get_rank_alerts, or start_ranking_run.

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

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

There is no when-to-use or when-not-to-use guidance and no alternative named. The word 'tracked' subtly implies it only covers keywords already being tracked (as opposed to start_ranking_run which would initiate tracking), but the agent must infer that on its own.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds value by naming the returned data sets (since there is no output schema), but says nothing about auth requirements, result limits, or empty-result 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 tight sentences with the purpose front-loaded and the return content following. No filler, though the trailing fragment style ('+ rival domains + AI-only rivals') is terse rather than structured.

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

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

For a low-complexity, single-parameter read tool with full annotation coverage, the description covers purpose and enumerated returns, which compensates for the absent output schema. Only minor gaps (pagination, limits, failure modes) remain.

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 exists and the schema documents it fully ('UUID of the site', 100% coverage). The description adds no format or constraint detail beyond the schema, which is the expected baseline when the schema does the work.

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

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

States a specific verb and resource ('Local SEO overview for a site') plus what it returns (local keywords, rival domains, AI-only rivals). It is clear what the tool delivers, though it does not distinguish itself from sibling readers like get_competitors or get_keyword_rankings.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternative sibling is named. The parenthetical '(rank-tracker with local intent)' hints at scope but leaves the agent to infer when this is preferred over other overview 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, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds a little by sketching the returned content categories (demand aggregates, concentration, provenance chips), but with no output schema present it stops short of describing structure, granularity, or time windows. Adds some value beyond annotations but not rich behavioral context.

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

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

A single front-loaded sentence that names the resource first and the payload second, with no filler. It is efficient, though the trailing enumerated clause is dense and slightly opaque ('provenance chips'), which costs 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?

With one simple required param and full annotation coverage, the interface side is adequately covered. However, there is no output schema, so the description nominally carries the burden of explaining returns and it only gestures at them via three vague noun phrases, leaving the agent without a concrete sense of shape or scope.

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 (site_id) and schema description coverage is 100%, so the schema fully documents it. The description adds no syntax, format, or scoping detail about site_id beyond what the schema provides, which is the expected baseline when the schema does the work.

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

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

States a clear resource (market analysis overview for a site) and enumerates what it contains: tracked keyword demand aggregates, competitive concentration, and provenance chips. It's distinguishable from generic siblings like get_site, but it doesn't explicitly separate itself from near-neighbors such as get_competitors or get_keyword_gaps, so sibling differentiation is only implicit.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives. An agent cannot infer from the text whether to call this versus get_competitors or get_keyword_gaps for competitive or demand data.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds substantive context beyond that: it discloses the exact categories of data returned (USD/INR pricing, site limits, credits, trial state) and that pricing_url is where purchase occurs, which tells the agent this is a read-only informational snapshot with no side effects.

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

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

One dense sentence that front-loads the core purpose (plans + caller entitlement) before the payload enumeration. It is long but every clause adds a distinct data category, and there is no filler or restated title text.

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

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

There is no output schema, so the description must carry the return-value burden, and it does so thoroughly: catalogue contents, currency variants, limits, credits, features, entitlement state, and the purchase URL. Combined with annotations covering the safety profile, an agent has everything needed to call and interpret this tool.

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

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

The tool takes zero parameters, so the schema-baseline of 4 applies; there is nothing for the description to clarify beyond what the empty schema already establishes. The description correctly implies the call is context-scoped to the caller rather than parameterized.

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 (retrieves Pylon SEO plans plus the caller's entitlement) and enumerates the concrete payload: paid catalogue tiers, currencies, site limits, credits, features, current plan, usage, trial state, and purchase URL. It is clearly distinguishable from the many analytical siblings like get_site, get_score_history, or get_gsc_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?

Usage is implied by the content (call when you need plan/pricing or entitlement context), but there is no explicit when-to-use statement, no prerequisites, and no routing to or away from alternatives. The agent must infer the trigger condition from the resource description alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the shape of the research payload, which is genuinely useful, but says nothing about freshness, per-prompt granularity limits, or how the research is scoped to the site.

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

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

One sentence with a compact parenthetical enumeration of return fields; no filler. Front-loading is acceptable, though the absence of an explicit verb makes the opening slightly less actionable than it could be.

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

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

For a single-parameter read-only tool with no output schema, the description usefully enumerates the returned concepts, which compensates for the missing return documentation. It stops short of complete routing guidance among the AI-visibility siblings, which is the main 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% for the single site_id parameter (UUID of the site), so the schema carries the burden. The description adds no format, defaulting, or scoping detail 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 names the resource (per-prompt AI research for a site) and the payload fields (target share, leader, rivals, opportunity bucket), so an agent can tell what it returns. It is a noun phrase rather than a verb+resource, and it does not distinguish itself from AI-visibility siblings like get_ai_visibility or get_ai_overview_presence.

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 statement of when to use this tool versus the many adjacent AI/visibility siblings in the list. There are no prerequisites, exclusions, or alternative-routing hints — the agent must infer the use case entirely from the name.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered without the description. The description does add useful payload signal (thresholds plus is_active flags), but says nothing about ordering, whether disabled rules are included, or how many rules come back.

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

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

A single front-loaded sentence that leads with what the tool returns and appends the payload shape in parentheses. No filler and nothing misplaced.

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 one-parameter read whose annotations already establish it as safe and idempotent, the description is nearly sufficient — it tells the agent what the resource is and what fields come back. Only the lack of output schema and any note about non-active rules leaves a small 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% for the single site_id parameter, so the schema carries the semantics. The phrase 'for a site' loosely echoes the required parameter but adds no format or constraint detail beyond it; baseline 3 applies.

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

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

The description names a specific resource — configured rank-drop alert rules for a site — and even sketches the returned fields (thresholds, is_active flags). It does not, however, distinguish itself from the sibling add_rank_alert, which an agent could confuse as the counterpart 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?

There is no when-to-use guidance and no named alternative. The reader must infer from the name and the sibling list that this is the read side of add_rank_alert; the description itself offers no routing or exclusion criteria.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context by naming the returned fields (status code, response time, size, depth, indexable) and the 200-row window, but it does not explain ordering, how to reach older pages, or whether the window is a hard cap versus a page size.

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

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

One tight sentence with the resource and scope front-loaded, plus a short constraint clause. Nothing is wasted, though 'Windowed at 200 rows' is slightly terse relative to the limit parameter's own 1-200 range.

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

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

With no output schema, the description carries the burden of describing returns; it partially does so by listing the columns but omits record shape, ordering guarantees, and how to page beyond the newest window. Adequate for a simple read tool, but gaps remain for an agent planning a multi-call crawl analysis.

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 site_id and limit, so the schema already carries the parameter semantics. The description mentions the 200-row window but adds no meaning beyond what the limit property already documents.

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: retrieving page-level records from a site's most recent crawl. That distinguishes it from audit/issue siblings like get_site_audit and get_audit_issues, though it never names a sibling explicitly to sharpen the boundary.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. 'Latest crawl' implies a scope but not a selection condition, so an agent must infer whether this or get_site_audit is the right call.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond them: daily granularity and the truncation limit ('most recent 90 samples'), which tells the agent the return is bounded.

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

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

Two short sentences with zero waste; the resource and scope are front-loaded and the sample limit follows immediately. Nothing redundant or padded.

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

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

For a single-parameter read tool with rich annotations and no output schema, the description covers purpose, granularity, and result size. Minor gaps remain (ordering, date semantics, whether samples are calendar-daily or scan-daily), but nothing critical is missing.

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

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

Schema coverage is 100% with a single site_id documented as the site UUID, so the schema carries the parameter burden. The description adds no parameter-level detail beyond what the schema already provides, making baseline 3 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+resource ('Daily audit score history for a site') and clarifies the intent ('used for trend lines'). It is distinct from siblings like get_site_audit or get_audit_issues, though it doesn't explicitly name the sibling it differs from.

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?

'Used for trend lines' implies the usage context but gives no explicit when-to-use vs. alternatives or exclusions. An agent can infer it is for historical trending rather than point-in-time audit data, but nothing is stated directly.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered. The description adds useful context about the data source ('latest ranking run') and aggregation granularity, but says nothing about output shape, counts vs. booleans, or whether data can be stale.

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

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

A single front-loaded sentence that names the operation, the subject, the feature list, and the data scope with zero filler. 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 single-parameter aggregation tool with no output schema, the description conveys what is aggregated and over what scope. It could go slightly further on return format (e.g., presence counts per feature), but nothing essential for 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?

Only one parameter with 100% schema coverage, so the schema fully documents site_id. The description implies the site scoping ('across the site's tracked keywords') but adds no new semantics beyond what the schema already provides, so the baseline of 3 applies.

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

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

States a specific verb ('Aggregate') plus resource ('SERP-feature presence') and scopes it ('across the site's tracked keywords, from the latest ranking run'), even enumerating the features covered. It is a broad superset that implicitly differs from narrower siblings like get_ai_overview_presence, but it never names or contrasts any sibling explicitly.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives such as get_ai_overview_presence or get_ai_visibility that overlap with this feature set. The only contextual hint is 'from the latest ranking run', which concerns data freshness rather than usage.

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

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

The annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world behavior. The description adds context by listing the metadata fields returned, which is useful because there is no output schema, but it does not disclose error behavior, authorization needs, or other operational traits.

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

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

The definition is a single, front-loaded sentence that identifies the resource and enumerates the key returned fields with no wasted words.

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

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

For a simple single-resource read, the description is nearly complete: it enumerates the metadata fields returned, compensating for the missing output schema. It does not mention error cases or how to obtain site_id, but those gaps are minor given the tool's simplicity and schema clarity.

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

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

Schema description coverage is 100%, and the single site_id parameter is fully documented in the schema as a UUID. The description adds no further parameter meaning beyond what the schema already 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 states a specific verb and resource ('Get one site's metadata') and lists returned fields, making the purpose clear. However, it does not explicitly differentiate from the sibling list_sites or name any alternative, so it falls short of full sibling differentiation.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no routing to alternatives such as list_sites. Usage is only implied by the required site_id parameter.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds useful context by disclosing what the call returns (aggregate scores plus issue counts bucketed by severity), which is notable given there is no output schema; it does not mention auth or rate limits, hence not 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?

One compact sentence that front-loads what the tool retrieves and then enumerates the returned shape; nothing is padded or repeated.

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

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

For a single-parameter read tool with no output schema, the description covers both the identity of the resource and the structure of the result, which is enough to call it correctly. Auth/permission expectations and whether a prior audit must exist are the only unstated assumptions.

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

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

Schema description coverage is 100% and there is a single required site_id documented as the site UUID, so the schema carries the semantics. The description adds no parameter-level detail beyond it, which is the expected baseline.

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

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

States a specific verb (get) and resource (latest SEO audit run for a site) plus the scope of the payload (overall + per-category scores and issue counts by severity). An agent can distinguish this from get_audit_issues or get_score_history, though no sibling is named explicitly.

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

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

The word 'Latest' hints at currency, but there is no explicit when-to-use guidance, no conditions or prerequisites, and no routing to alternatives like get_audit_issues (issue-level detail) or get_score_history (trends).

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description still adds real behavioral context beyond them: the change set is computed as a diff between the two most recent crawls and is scoped to six specific SEO attributes. It does not cover result limits, ordering, or behavior when fewer than two crawls exist.

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

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

A single sentence that front-loads the operation and the comparison window, then lists the change scope in a compact parenthetical. No filler, no restatement of the name or title.

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

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

With no output schema, the description must convey what comes back, and it does by naming the six compared attributes plus the two-crawl comparison basis. It leaves unstated the response shape (per-URL diff? counts?), ordering, and the zero/one-crawl edge case, so it is strong but not fully self-contained.

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% (site_id is documented as 'UUID of the site'), so the schema carries the parameter semantics. The description adds nothing about the parameter, so the baseline 3 for a schema-documented single-parameter tool 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 ('Recent SEO changes detected') and enumerates the change categories (title / meta / h1 / canonical / indexability / status code), so an agent can distinguish it from siblings like get_site_audit or get_scan_pages. It stops short of naming an alternative, so it is clear but not sibling-differentiating.

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 'between the two most recent crawls' implies the precondition (at least two completed crawls) and frames this as a delta tool rather than a snapshot, which is useful implicit guidance. However, it never states when to pick this over get_site_audit / get_scan_pages / get_score_history, and no 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 declare readOnly, idempotent, non-destructive, non-openWorld, so the safety profile is covered. The description adds the tenant-scoping constraint ('caller's organisation'), which is useful auth/visibility context. It stops short of describing ordering or return shape.

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

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

Two tight sentences, with the resource and scope front-loaded and the filters following. No filler, though the filter list is dense enough that it slightly crowds the sentence.

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

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

For a simple read-only list tool with full schema coverage, no output schema and rich annotations, the description covers resource, scope, and filters. Ordering and return-shape details are absent but are minor for this tool class.

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 the actual enum values for `kind` (overview|seo_audit|rankings|competitors|ai_visibility) that the schema merely labels 'Optional kind filter' – genuine value beyond the structured field.

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

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

States a specific verb (List) and resource (stored report runs) scoped to the caller's organisation, which separates it from the many get_* single-resource siblings. It is clear, though it doesn't explicitly contrast with the nearest alternative, get_score_history.

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 naming the two optional filters, but there is no explicit when-to-use / when-not-to-use guidance or reference to an alternative tool. Adequate but with a clear gap.

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

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

Annotations already declare readOnly, idempotent, non-destructive and non-openWorld, so the safety profile is covered. The description adds the useful behavioural detail that this is a discovery/prerequisite call and lists the fields returned, though it says nothing about pagination or result-size limits.

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

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

Two sentences, no filler, with the discovery-first directive front-loaded after the purpose statement. Every clause carries information an agent needs.

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

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

For a zero-parameter list tool with full annotation coverage, the description covers purpose, usage order and returned fields. The only gap is pagination/result-size behaviour, which matters slightly for a list endpoint with no output schema.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the enumerated return fields are a bonus rather than parameter guidance.

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

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

States a specific verb and resource ('List every SEO site') plus the scope ('in the authenticated user's organisation'), which clearly separates it from the singular sibling get_site. It even enumerates the returned fields, so an agent knows exactly what this call yields.

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 ordering directive: 'Use before any other tool to discover which site_ids are valid.' That tells the agent both when to call it and why, since site_ids are prerequisites for the other tools in the set.

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

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

Annotations already declare readOnly, idempotent, open-world and non-destructive, so the safety profile is covered. The description adds genuinely new context: it is rate-limited per anonymous identity and returns the same audit shape authenticated users receive, which helps an agent anticipate throttling and output structure.

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 with no filler, and the core purpose plus the 'public/anonymous' scoping is front-loaded before the secondary notes on output and rate limits.

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 one-parameter read-only tool with full schema coverage and rich annotations, the description covers purpose, output shape and a rate-limit caveat. No output schema exists, but the description gestures at the return shape, so the remaining gap is minor.

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

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

There is a single parameter at 100% schema description coverage, so the schema already documents the url argument with an example format. The description adds nothing about the parameter beyond what the schema provides, 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 ('Run the anonymous single-URL SEO checker') with a clear scope qualifier (public, single URL). It implicitly distinguishes itself from the authenticated scan sibling via 'Returns the same audit shape logged-in users see', but never names that sibling (e.g. start_scan), so differentiation is inferred 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 'anonymous/public' framing implies this is the right tool when no credentials are available and the logged-in scan is the alternative, but it never states when to use this versus start_scan. Usage is implied, not spelled out, and no exclusions or prerequisites are given.

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

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

Annotations already declare non-read-only, non-idempotent, non-destructive, closed-world behavior. The description adds the critical extra fact that this is asynchronous ('Enqueue... resolves'), which no annotation conveys and which changes how an agent should treat the call. It does not say how to poll status or whether repeat calls spawn duplicate 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?

A single tight sentence, front-loaded with the action verb and the async nature, with no filler.

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

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

For a one-param job-trigger tool with annotations covering the safety profile and no output schema, this is nearly complete. The remaining gap is that it doesn't indicate how the resulting run is observed or that non-idempotent repeats create separate runs.

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 coverage is 100%, so the schema already fully documents site_id as a site UUID. The phrase 'for a site' adds only marginal confirmation. Baseline 3 applies when the schema does the work.

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

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

States a specific verb (enqueue) plus resource (keyword-rankings sweep) and scope (one site, all tracked keywords' SERP positions). This clearly separates it from the read-side sibling get_keyword_rankings, though it never names that sibling explicitly.

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

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

Usage is implied: you call this to trigger a fresh sweep, versus get_keyword_rankings to read stored positions. No explicit when/when-not conditions, prerequisites, or named alternatives 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 idempotentHint=true, readOnlyHint=false and destructiveHint=false, but the description adds concrete semantics the annotation does not: a running or queued run 'short-circuits,' so the caller learns that a second call will not spawn a duplicate job. 'Enqueue' also signals asynchronous, non-immediate execution. It does not cover rate limits, credit/cost implications, or how to observe progress.

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, zero filler, with the core action front-loaded and the idempotency caveat second. Nothing could be removed without losing information.

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

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

For a trigger tool with no output schema, the description says nothing about what the call returns (e.g., a run/job identifier) or how to follow up — get_scan_pages, get_site_audit, get_score_history are the obvious polling siblings and go unmentioned. Annotations cover the safety profile and the single required parameter is fully documented, so it is adequate but leaves a real observability 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?

Only one parameter (site_id) and schema description coverage is 100%, with the schema itself stating 'UUID of the site.' The description adds 'for a site' but no format, sourcing, or validation detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'Enqueue a fresh crawl + audit run for a site.' An agent can tell this triggers a scan rather than reading results, which separates it from the many get_* siblings. It stops short of naming the closest alternatives (run_public_scan, start_ranking_run), so the boundary is inferred rather than stated.

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

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

Usage is implied — call this to kick off a crawl/audit for a known site — and the idempotency note hints that duplicate calls are harmless. However, there is no explicit when-to-use versus run_public_scan or start_ranking_run, and no stated prerequisites (e.g., site must already exist / be verified).

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds the verified-key and same-host constraints, but omits what 'destructive' means in practice (external submission to third-party engines), any rate/batch limits, and the preview-first safeguard.

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

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

Two sentences, zero filler, with the action and its target front-loaded before the constraints. Every clause carries information an agent needs.

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

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

Covers purpose and prerequisites, and annotations handle the safety profile, so the core is present. For a destructive, non-idempotent external submission with no output schema, however, it leaves out what a successful or failed submission looks like and any batch/rate constraints.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a real constraint not in the schema: all URLs must share the site's host, which governs how the urls array is populated. It does not explain the confirm_token preview/submit semantics, which the schema already handles.

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 ('Push'), the resource ('URL batch'), the target service family (IndexNow, with the search engines named), and the scoping unit ('for a site'). No sibling tool overlaps with search-engine submission, so the agent can identify it immediately.

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 hard prerequisites (an existing verified IndexNow key, URLs sharing the site's host), which is genuinely useful, but says nothing about when to prefer this over other actions or about the preview-then-submit workflow — that distinction lives only in the confirm_token schema description.

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