Crawlwise

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

Annotations only declare the mutation/open-world profile; the description adds substantial behavior: the job_id return contract, the required polling loop, the three finding buckets, the explicit non-measurement list, the no-invented-scores guarantee, and check-id traceability. This is exactly the operational context an agent needs to drive an async job and interpret results honestly.

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

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

Four short sentences, front-loaded with the action and the return contract before the follow-up workflow and scope caveats. Every sentence carries information, though the capitalization-heavy negative clauses read as a slightly disjointed list.

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

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

With no output schema, the description carries the burden of explaining returns and does so: job_id plus the grouping scheme for findings. Combined with the explicit non-scope list and the polling instruction, an agent has everything needed to invoke and consume this tool correctly.

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

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

The description never mentions 'url' or 'site_id', adding zero semantic detail beyond the schema. With only 50% schema coverage, site_id is completely undocumented in both places, and the required url's format constraints come solely from the schema. At mid coverage the description should have compensated and does not.

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 ('Start a full page audit') and immediately clarifies the async nature by noting it returns a job_id. The negative-scope sentence distinguishes it from rank/traffic/backlink tools that an agent might otherwise confuse it with, and the get_audit handoff separates it from the polling sibling.

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

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

Gives a clear two-step workflow: start here, then poll with get_audit until status is complete, which is explicit routing to the correct alternative. It also enumerates what the tool does not cover, ruling out misselection. It does not compare against the site-level sibling crawl_site, so page-vs-site selection is left implicit.

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

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

Annotations already establish readOnly, idempotent, non-destructive and open-world behavior, so the bar is lower. The description adds real context beyond them: the enumeration of result states and the caveat that a 200 status reflects crawler reachability rather than visibility, which prevents misreading the result.

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

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

Three short sentences, front-loaded with the action and result states, then the scope exclusion and the 200 caveat. Every sentence carries information; only the caveat could arguably be trimmed.

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 probe with no output schema, the description supplies the missing return-value vocabulary (allowed/blocked/challenged/not established) plus the key interpretation caveat. Nothing essential is absent, though it does not mention rate limits or behavior on unreachable/invalid URLs.

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 only one parameter and schema description coverage is 100% ('Public http(s) URL'), so the schema carries this dimension. The description adds no extra meaning such as redirect handling, auth-protected URLs, or timeout behavior, making 3 the correct 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?

Names a specific verb and resource ('fetch the URL as GPTBot, ClaudeBot and other AI crawlers') and states the exact output states (allowed/blocked/challenged/not established). This distinguishes it from siblings like audit_page and crawl_site without opening any schema.

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

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

Explicitly bounds scope with 'Does NOT measure whether a model would cite the page, brand mentions, or ranking in ChatGPT' and warns that 'a 200 is reachability, not visibility', which tells an agent when this tool's answer is not the answer the user wants. It stops short of naming which sibling to use instead (e.g. audit_page) for those questions.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive call, so the safety profile is covered. The description adds genuine behavioral context beyond that: the field-vs-lab data limitation and the 'not_measured, never 0' sentinel convention for missing lab metrics, which is essential for interpreting results.

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 tightly scoped sentences with the core purpose front-loaded, followed by two scope exclusions and one return-value caveat. No filler, and each sentence carries information an agent needs.

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

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

With no output schema and only 50% parameter coverage, the description does most of the heavy lifting: it defines scope, data limitations, and result semantics. It is nearly complete, missing only hints about what metrics are returned or the latency/cost profile of a PageSpeed Insights call.

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

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

Schema coverage sits at 50%: 'url' is documented but the 'strategy' enum carries no description. The phrase 'one URL and one strategy' implies the single-value cardinality of both parameters, but adds no syntax or value meaning beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Core Web Vitals via PageSpeed Insights') and precisely bounds scope to 'one URL and one strategy', which separates it from site-wide siblings like crawl_site and audit_page. It stops short of naming an actual sibling, so differentiation is achieved only by negative scope statements.

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?

Two explicit exclusions carve out when this tool is wrong: it does not measure field (CrUX) data unless PageSpeed supplies it, and it does not audit the rest of the site. That is clear usage context, but the description never names the alternative tool an agent should reach for instead.

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

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

Annotations already cover the safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false). The description adds genuinely useful behavior beyond that: it returns a crawl id immediately (asynchronous start) and stops at the plan page cap, which explains partial results. The orphan not_measured edge case is a nice detail.

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

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

Four short, front-loaded sentences with no filler; the purpose leads and the constraints follow. 'Does NOT crawl the whole internet' is slightly obvious but does earn its place as scope bounding.

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 helpfully explains the return value (crawl id) and the async nature. However, for a tool whose schema documents zero parameters, the absence of any parameter guidance leaves the definition incomplete for correct invocation.

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

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

Schema description coverage is 0% and the description explains none of the three parameters. 'pages', 'site_id', and 'allow_subdomains' are left entirely undefined, and the vague reference to a 'plan page cap' does not clarify how 'pages' relates to it. This is a real gap the description should have filled.

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 ('Start a multi-page crawl of a site') and bounds scope by declaring what it does NOT do (keyword/rank checks, whole-internet crawling). This lets an agent distinguish it from audit_page and check-related siblings, 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?

Gives a clear precondition ('a site you own') and explicit exclusions ('Does NOT run keyword or rank checks'), which helps an agent route keyword/rank work elsewhere. It stops short of naming the alternative tool or stating when to prefer this over audit_page.

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 partly covered. The description still adds real value by enumerating exactly which side effects do NOT occur (no charge, no job, no reservation), which directly addresses an agent's fear about calling a cost tool. It omits return shape and any rate/permission notes.

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

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

Four short sentences, front-loaded with the core meaning and free of padding. The three negation clauses are mildly redundant in tone but each targets a distinct concern, so the text still earns its length.

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

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

With no output schema and low parameter coverage, the description should carry more. It adequately implies the return value (a credit figure) and rules out side effects, but leaves the key required 'operation' parameter and 'units' undefined, so an agent cannot fully construct a correct call from the definition alone.

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

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

Schema description coverage is only 33%: url is documented, but 'operation' (the sole required parameter) and 'units' are not, and there is no enum to constrain operation. The description says cost is 'per operation' but never explains what values operation accepts or what units means, so it fails to compensate for the coverage gap.

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

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

The description states a specific outcome: the credit cost an operation would incur for this account. It is clearly distinguishable from get_credits (balance) and crawl_site (action), but it never names a sibling to route the agent, 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?

Usage is implied rather than stated: the three negative clauses ('Never charges', 'Never creates a job', 'Does NOT reserve credits') make clear this is a safe dry-run pre-check. There is no explicit when-to-use or when-not-to-use guidance and no mention of how it relates to get_credits or the tools whose costs it estimates.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful output-behavior context: it does not add advice beyond what is already on the check, and a not_measured check is treated as the answer. These are meaningful behavioral disclosures beyond annotations.

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

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

Three short sentences with no wasted words. The core purpose is front-loaded, followed by useful clarifying constraints.

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 lookup with annotations covering safety, the description is mostly adequate. However, with no output schema and 0% parameter description coverage, it does not explain what 'full detail' contains or fully clarify the audit_id parameter.

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

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

Schema description coverage is 0%, so the description must carry all parameter meaning. It clarifies check_id as the check to explain, but audit_id is only implied by 'from an audit job or report' and its format, source, and relationship to check_id are not specified.

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

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

States a specific resource and scope: full detail for one check id from an audit job or report. This distinguishes it from sibling tools like get_audit or get_crawl_issues by focusing on a single check, though it does not explicitly name alternatives.

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

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

Implies the tool is used to retrieve detail on a specific check id, and clarifies a not_measured edge case. However, it provides no explicit when-to-use guidance, no exclusions, and no routing to sibling tools for broader audit or crawl 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description adds genuine value by disclosing two non-obvious boundaries: no live-page fetch and no site-wide uniqueness checking. It omits that all inputs are optional and what the generated output looks like.

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, zero filler, with the positive purpose front-loaded and the caveats following. 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?

The negative constraints are a real addition for a tool with no output schema, but the definition is silent on parameter meaning, formatting, and return shape. Adequate but leaves clear gaps for a 3-parameter generator.

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 0% and the description only says 'the fields you supply' without naming title, canonical, or description or giving format expectations. With three undocumented parameters, the description fails to compensate for the schema gap.

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

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

Specific verb+resource ('Generate HTML meta tags') with an immediate scoping clause ('from the fields you supply'). This distinguishes it from live-fetching siblings like audit_page or crawl_site, 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?

Two explicit negative constraints ('Does NOT fetch the live page', 'Does NOT check uniqueness across the site') tell the agent when this tool is the wrong choice, which is unusually useful for routing. It stops short of naming the alternative tool to use instead.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: the output is synthesized, never fetched from a live site, and no crawl-access guarantee is implied.

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, zero filler, with the core action front-loaded and the two limitations trailing as clarifiers. Every sentence earns its place.

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

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

For a deterministic generation tool whose annotations already carry the safety profile and which has no output schema, the description is largely sufficient. The only soft gap is an unstated hint about the return format (robots.txt text), which is fairly self-evident from the name.

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?

Top-level schema coverage is 0%: "rules" and "sitemaps" carry no schema descriptions, and only the nested "agents" field is annotated. The description says merely "rules you supply" and adds no meaning about structure, allow/disallow semantics, or sitemap format, so it fails to compensate for the coverage gap.

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

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

The description gives a specific verb and resource ("Generate a robots.txt") and its negative clauses ("Does NOT fetch the live robots.txt") implicitly separate it from fetch/audit siblings like check_ai_crawlers. It stops short of naming an explicit alternative, so it does not fully earn a 5.

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

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

Usage is only implied: the agent can infer it should call this when it already holds rules to write out. There is no explicit when-to-use, no named alternative, and no statement of prerequisites, which keeps it at minimum-viable.

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 two genuinely useful scope limits beyond that: it performs no page fetch (so fields must be supplied by the caller) and no eligibility validation. It does not describe the output format or failure modes.

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, zero filler, with the capability stated first and the exclusions immediately after. Every sentence earns its place by carving out a boundary or naming an alternative.

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

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

There is no output schema, and the two-parameter schema has 0% description coverage with a nested object, so the description should do more to explain the `kind`/`fields` contract. It covers behavior adequately but leaves the shape of the primary input under-specified.

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

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

Schema description coverage is 0%, so the description must carry the burden and largely does not. It implies `fields` is caller-supplied input and that `kind` names a schema.org type, but gives no format, accepted values, or expected structure for the nested `fields` object.

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 (Generate) and resource (JSON-LD for a schema.org type) plus the input source (the fields you supply). It also names the sibling it is not: validate_schema. An agent can distinguish it from validate_schema and generate_meta_tags without opening a schema.

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

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

Explicitly states two things the tool does NOT do (fetch the live page, validate eligibility) and routes the validation case to the named alternative, validate_schema. The positive trigger is front-loaded in the first sentence, so when-to-use and when-not-to-use are both covered.

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

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

Annotations already cover read-only/idempotent/no-destructive, but the description adds meaningful behavior beyond them: it is a polling endpoint with a documented retry condition, it does not charge credits, and it does not fabricate checks. The 'empty group means none, not that the site is perfect' line prevents a specific agent misreading of results.

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

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

Front-loads the action and prerequisite, then adds short clauses for retry, exclusions, and result semantics. Every sentence carries distinct information with no filler.

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

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

No output schema exists, and the description compensates by describing the finding groupings. For a 2-parameter tool the only real gap is the unexplained audit_id, which is a minor omission given how much else is covered.

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

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

Schema coverage is 50% and the description only reinforces job_id ('Pass the job_id', already in the schema). The second parameter, audit_id, is undocumented in both the schema and the description, so an agent has no guidance on when it is needed or how it differs from job_id.

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 ('Poll an audit started with audit_page'), and its retrieval scope (findings grouped as priority / worth considering / not measured). It explicitly distinguishes itself from the sibling that starts audits, so an agent can route between audit_page and get_audit without opening schemas.

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

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

Gives explicit control-flow guidance ('When status is running, call again'), names the prerequisite (the job_id from audit_page), and states exclusions ('Does NOT start a new audit'). The when-to-use and when-not-to-use conditions are both spelled out.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral value beyond that: findings are strictly observational ('Does NOT invent issues the crawl did not observe') and empty-list semantics are defined, which prevents misreading an empty result as success.

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, each carrying distinct load: scope and finding types first, then the non-invention guarantee, then empty-result semantics. No filler and the purpose is front-loaded.

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

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

With no output schema, the description reasonably conveys the return shape (a list of categorized findings) and the empty case. It omits ordering, pagination, and what happens with an invalid or unfinished crawl_id, but nothing critical to calling it 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 0% and the sole parameter crawl_id is undocumented in both schema and description. The phrase 'from a finished crawl' is a weak semantic hint that the ID must reference a completed crawl, but no format, source, or validity constraint is given.

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 ('Cross-page findings from a finished crawl') and enumerates the finding types (duplicate titles, redirect chains, broken links, orphans). It implicitly separates itself from the page-level sibling audit_page, but 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?

Usage is implied by the precondition 'from a finished crawl', which tells the agent this must follow crawl_site. However, it never says when to reach for this versus audit_page, get_audit, or explain_finding, so routing is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false. The description's "Does NOT change the balance" largely restates readOnlyHint in prose, but "Does NOT show other accounts" adds a genuine scope constraint not present in annotations. Useful but not rich additional 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?

Three short sentences, front-loaded with what is returned before the negatives. Slightly padded by the read-only restatement that annotations already cover, but nothing is bloated.

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

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

For a zero-parameter, read-only account query with no output schema, the description adequately conveys the return content (balance plus recent spend) and the account scoping. Return shape details (format, time window of "recent") remain unspecified but are minor at this complexity.

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; the baseline for a no-parameter tool applies. No parameter guidance is needed or missing.

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

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

States the resource (credit balance) and the extra payload (recent spend) in a specific way, so an agent knows immediately what comes back. It does not, however, differentiate itself from money-adjacent siblings such as estimate_cost, so the routing value is partial.

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 two negative statements scope what the tool will not do, but there is no statement of when to call it versus alternatives (e.g. estimate_cost for projections). Usage must be inferred from the purpose line.

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 genuine boundary context beyond that: it can legitimately return an empty list, it will not invent links to pages the crawl never saw, and it will not modify copy — all useful expectations to set for an agent.

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

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

Four short, front-loaded sentences with no filler; the core purpose leads and the constraints follow. 'Does NOT rewrite your copy' is slightly tangential but still clarifies scope rather than padding.

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

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

There is no output schema, and the description does cover the notable return case (empty list) and key non-behaviors, which is good. What is missing is how to obtain a valid crawl_id (presumably from crawl_site or get_audit) and any hint about the shape of the suggestions returned.

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

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

Schema description coverage is 0%, so the description must carry meaning for crawl_id. It implies the id must reference a finished crawl, which adds some semantic constraint, but does not say where the id comes from or what an invalid/unfinished id yields.

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 ('internal-link suggestions') and scopes it to a finished crawl, so the agent knows this is a retrieval, not a generation, tool. It does not name any sibling to differentiate from (e.g., get_crawl_issues), which keeps it 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?

'From a finished crawl' implies the precondition that a crawl must already have completed, which is useful guidance. However, it never states when to prefer this over sibling tools like get_crawl_issues or audit_page, nor what to do if the crawl is not yet finished, leaving usage to inference.

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

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

Annotations already declare read-only, idempotent, non-destructive, and closed-world behavior. The description adds genuine value beyond this by ruling out a side effect ('Does NOT verify domains') and clarifying account scoping, which is not derivable from structured fields.

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

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

Three short sentences, front-loaded with the core action and free of filler. Tight and readable, though the two 'Does NOT' clauses read slightly as defensive padding.

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

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

For a simple read-only lister with annotations covering the safety profile and no output schema, the description is adequate on scope and side effects. However, it omits the one parameter's meaning and any indication of the returned shape or pagination.

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

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

With one parameter (include_archived) and 0% schema description coverage, the description carries the burden of explaining it but never mentions it. The default behavior for archived sites is left entirely unstated.

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 sites on this account') and scopes it to the account, distinguishing it from per-site tools like crawl_site and check_vitals. It doesn't explicitly name a sibling alternative, so it falls short of a 5.

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

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

The negative clarifications ('Does NOT include other users', 'Does NOT verify domains as a side effect') imply usage context, but the description never states when to reach for this tool versus related ones. Usage is only implied.

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

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

Annotations already cover readOnly/idempotent/non-destructive, so the bar is lower; the description adds meaningful context beyond them, namely that it evaluates eligibility rather than real SERP outcomes and that FAQPage is treated as not a rich-result opportunity. This is genuinely informative behavior detail not present in structured fields.

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

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

Three tight sentences, purpose front-loaded, and every sentence carries scope information rather than filler. No redundancy with the title.

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

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

For a validator with no output schema, the description should convey what comes back (eligibility report shape) and how the two input modes work; it hints at output semantics (FAQPage reported as not an opportunity) but omits return structure and parameter usage. Adequate given the annotations but with clear gaps.

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

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

'json' is undocumented in both schema and description, and at 50% coverage the description does not compensate — it never explains that the markup to validate is passed via the json parameter or that url and json are the two accepted input forms. The description's mention of JSON-LD is suggestive but not tied to the parameter.

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 precise verb (validate) and resource (JSON-LD / schema.org markup) with the scope of validation (Rich Results eligibility). It does not explicitly distinguish itself from the sibling generate_schema, so it stops short of a 5, but an agent can still tell the two apart conceptually.

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

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

Provides clear negative scoping — it does not submit to Google and does not measure actual rich-result appearance — which routes the agent away from expecting live/publishing behavior. It lacks an explicit positive 'use this when' clause or a direct pointer to generate_schema for the create case, so not a 5.

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