Crawlwise

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

With no annotations, the description carries the full burden and does so well: it discloses the asynchronous job pattern, the return value (job_id), the required polling loop, the finding grouping scheme, explicit exclusions, and an anti-hallucination guarantee ('Does NOT invent scores. Every action cites a real check id'). This is unusually rich behavioral context for a mutation-starting tool.

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

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

Front-loaded with the core action, followed by the polling instruction and scope exclusions. Every sentence earns its place; no filler or restatement of the name.

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 compensates by explaining the immediate return, the polling target, and the shape of findings. The only real gap is the unexplained site_id parameter, which leaves some ambiguity for a 2-parameter 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 50% — 'url' is documented but 'site_id' has no description anywhere. The description adds no meaning about either parameter (no format, no when site_id is required, no interaction with url), 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?

States a specific verb+resource ('Start a full page audit') and immediately clarifies the async contract ('Returns a job_id immediately'). This distinguishes it from synchronous siblings like check_vitals or validate_schema without needing to open 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 names the follow-up workflow ('Poll with get_audit using that job_id until status is complete') and gives negative scope ('Does NOT measure keyword ranks, backlinks, traffic, or Search Console data'), which routes the agent away from this tool for those needs. It does not explicitly contrast with crawl_site or check_vitals, so it stops short of full when/when-not coverage.

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

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

With no annotations, the description carries the burden and does so well: it discloses the request is made under AI-crawler user agents and enumerates the four possible verdicts. The closing line 'A 200 is reachability, not visibility' usefully prevents misreading the result, though auth needs and rate/timeout behavior remain unstated.

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, front-loaded with the action and outcome set, then the scope exclusions and the interpretation caveat. No filler or repetition.

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

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

There is no output schema or annotations, so the description must cover the return semantics — and it does by naming the four verdicts and warning against reading a 200 as visibility. It is nearly complete for a one-parameter diagnostic tool, missing only latency/auth/pagination context.

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 ('Public http(s) URL'), so the schema already documents the only input. The description adds nothing about URL format or constraints beyond that, 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 (Fetch), a specific impersonation method (as GPTBot, ClaudeBot and other AI crawlers), and the exact reportable outcomes (allowed/blocked/challenged/not established). This clearly separates it from siblings like audit_page and crawl_site, which do not adopt crawler user agents.

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 draws firm negative boundaries — it does NOT measure citation likelihood, brand mentions, or ChatGPT ranking, clarifying when the result should not be interpreted. It stops short of naming which sibling to use for those related needs, so it is clear context without a routed alternative.

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

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

With no annotations, the description carries the full burden and does useful work: it discloses the field-data caveat, the single-page scope, and the not_measured sentinel semantics for missing lab metrics. It omits operational traits like rate limits and PSI call latency, which would be relevant for a remote measurement tool.

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

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

Four short sentences, each front-loading a distinct constraint (scope, field data, site scope, sentinel value) with zero filler. The scope limitation leads the description, which is the right priority.

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 measurement tool with no annotations and no output schema, the description covers scope, data-source caveats, and the missing-metric convention. It does not describe the shape of the returned metrics, but with only two simple parameters the definition 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?

Schema coverage is 50%: url is documented in the schema and strategy is an enum that is largely self-explanatory. The description adds no format or constraint detail for either parameter, so with half the schema documented the baseline of 3 is appropriate.

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

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

States a specific verb ('check') plus resource ('Core Web Vitals') and names the data source (PageSpeed Insights) and scope ('one URL and one strategy'). This distinguishes it from audit_page and crawl_site, which cover broader auditing.

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 usage with two negative statements: it does not measure field/CrUX data and does not audit the rest of the site, implying the sibling crawlers/auditors are the right tools for those jobs. It stops short of naming the alternative tool explicitly, so it falls just below a 5.

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

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

With no annotations, the description carries the full burden and delivers real behavior: it returns a crawl id immediately (async), caps pages at the plan limit, and marks orphans as not_measured when capped. Auth specifics and rate limits are absent, but the operational traits given are substantive.

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 action and return behavior, then cleanly separated "Does NOT" constraints. No filler; every sentence adds signal.

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 or annotations, so the description must stand alone. It explains the immediate return (crawl id) but not how the crawl is later consumed—sibling get_crawl_issues is never referenced—leaving a real gap in the workflow for a 3-parameter 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 0%, so the description must define the three parameters. "Multi-page" and "plan page cap" loosely imply pages, and "site you own" hints at site_id, but allow_subdomains is never mentioned and no parameter is explained explicitly.

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 you own") and implicitly contrasts with single-page siblings like audit_page via "multi-page." Clear enough for routing, though it never names a sibling to distinguish from directly.

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?

"A site you own" establishes an ownership prerequisite, and the two "Does NOT" clauses (no keyword/rank checks, no whole-internet crawl) usefully bound when this tool applies. No explicit alternative is named, so it stops short of a 5.

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

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

With no annotations, the description carries the full burden and does well: 'Never charges. Never creates a job. Does NOT reserve credits.' It clearly discloses non-mutating, non-destructive behavior, though it does not mention authentication requirements or potential 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?

Three short sentences, front-loaded with the core purpose followed by key behavioral negations. Every sentence earns its place with zero waste.

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

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

The description covers purpose and behavioral transparency well, but omits any parameter semantics and usage guidelines. For a tool with three parameters and no annotations or output schema, more context is needed 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 33%, with only 'url' documented. The description does not explain the 'operation' parameter's valid values or the meaning of 'units', so it fails to compensate for the low schema coverage.

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

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

The description clearly states what the tool does: 'What an operation would cost this account, in credits.' It specifies the verb (estimate) implicitly and the resource (cost), but does not explicitly distinguish itself from siblings like get_credits or audit_page.

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

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

The description implies usage: use it to find out an operation's cost without side effects. However, it gives no explicit when-to-use guidance or alternatives, leaving the agent to infer the context.

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

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

With no annotations, the description carries the full burden and does disclose two useful traits: it does not synthesize advice beyond what is on the check, and a not_measured check returns that status as the answer. However, it omits the read-only nature and any error behavior (e.g. unknown check_id or audit_id).

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 purpose, then scope limit, then edge condition. Nearly 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?

No annotations and no output schema, and the description does not describe the shape of the returned detail. For a two-param read tool it is adequate but leaves the return content and parameter formats 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 coverage is 0%, so the description must compensate. It loosely characterizes check_id ('one check id') and audit_id ('from an audit job or report'), but neither parameter's format or source is specified fully.

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: it returns 'full detail for one check id from an audit job or report.' That is clear enough for an agent to know it produces a single finding's detail versus the whole audit, though it never names a sibling tool to sharpen the contrast.

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 'full detail for one check id,' but there is no explicit when-to-use or when-not-to-use guidance, and no alternative (e.g. get_audit, audit_page) is named for broader views. The not_measured note describes an output condition, not a routing decision.

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?

No annotations exist, so the description carries the full burden. It usefully discloses two behavioral boundaries (no live fetch, no site-wide uniqueness check), which is genuinely valuable context. However it says nothing about the output form, defaults for omitted fields, or truncation/escaping behavior for a generation tool.

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

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

Three short sentences, front-loaded with the action and immediately bounded by the exclusions. Every sentence earns its place 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?

With no annotations, no output schema, and no parameter documentation, the description is too thin for a 3-parameter generator — an agent cannot tell which fields are required, how omissions are handled, or what the returned markup looks like. The negative constraints are a good start but not sufficient.

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

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

Schema description coverage is 0% and the description only refers generically to 'the fields you supply.' Nothing explains what title, canonical, or description mean in the output, their expected format, or whether all are optional (required count is 0). This does not compensate for the documentation 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?

States a specific verb (Generate) and resource (HTML meta tags) plus the input basis ('from the fields you supply'). It does not name a sibling, but the negative scoping implicitly separates it from tools that operate on live pages such as audit_page or crawl_site.

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

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

The two 'Does NOT' clauses give explicit when-not guidance: it is a pure transformation over supplied input, not a page-fetching or site-wide analysis tool. What is missing is any positive trigger (e.g. 'use when you need a snippet for a new/edited page without crawling').

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

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

With no annotations, the description carries the full burden, and it does disclose two real behavioral limits: no live fetch and no guarantee that crawlers honour the output. That's meaningful, but it omits auth/permission needs, whether output is returned or written, and any 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?

Two short sentences, positive statement first, exclusions second. Every clause earns its place and nothing is 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?

A generator tool with an undocumented array-of-rules parameter, no output schema, and no annotations needs far more: the expected rule object shape and return format are absent, leaving the agent unable to call it correctly.

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

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

Schema description coverage is 0% and the parameters are non-trivial: 'rules' is an untyped array with no item shape, and 'sitemaps' is never mentioned in the description. The phrase 'rules you supply' adds no structural meaning, so the agent cannot construct a valid value from the description alone.

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

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

States a specific verb and resource ('Generate a robots.txt') plus a scope caveat ('from rules you supply'), which likely distinguishes it from the crawler-oriented siblings like check_ai_crawlers. It stops short of naming a sibling explicitly, so it lands at 4 rather than 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 constraints ('Does NOT fetch the live robots.txt') imply the tool is for authoring rather than inspecting an existing file, which partially routes the agent away from check_ai_crawlers. There is no positive statement of when to prefer this over audits or validators, and no prerequisites.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose two important traits: it is a pure generator (no live-page fetch) and performs no eligibility validation. However, it says nothing about what is returned, error behavior, or whether the produced JSON-LD is schema-validated for structure, leaving meaningful gaps.

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, the core action front-loaded, followed by two boundary statements. Every sentence earns its place 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 nested-object tool with zero schema coverage and no output schema, the description covers routing and scope boundaries well but leaves the fields-object shape and the response contents unexplained. It is adequate for invocation but not fully sufficient.

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

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

Schema description coverage is 0%, so the description must compensate. It does hint at both parameters — 'schema.org type' maps to kind and 'the fields you supply' maps to fields — but it gives no detail on the nested fields object structure, required keys, or accepted kind values, so compensation is only partial.

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 output artifact ('Generate JSON-LD for a schema.org type') and explicitly frames itself against the sibling it is not ('Does NOT validate eligibility; use validate_schema for that'). An agent can distinguish it from validate_schema without reading either schema.

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

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

Gives both when-to-use and when-not-to-use conditions: it generates markup but does not fetch the live page and does not validate eligibility, with validate_schema named as the alternative for validation. This is explicit routing, not 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?

With no annotations, the description carries the full burden and does well: it discloses no new audit is started, no charge is incurred, no checks are invented, and that an empty group means zero findings rather than a clean bill of health. It omits polling cadence/rate limits and error states, 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?

Front-loads the purpose and required argument, then stacks short, high-signal clauses. The choppy 'Does NOT...' repetitions are slightly verbose but each carries a distinct constraint, so little 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 and no annotations, the description supplies the return shape (findings grouped as priority / worth considering / not measured) plus the empty-group caveat, which is what an agent needs to interpret results. Error handling and the undocumented audit_id are the remaining gaps.

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

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

Schema coverage is 50%: job_id is documented in the schema as coming from audit_page and the description reinforces 'Pass the job_id'. The second parameter audit_id is left entirely unexplained in both schema and description, so the description only marginally compensates.

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

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

States a specific verb and resource ('Poll an audit'), names the originating sibling (audit_page) and explicitly negates the confusing alternative ('Does NOT start a new audit'). An agent can immediately tell it apart from audit_page or check_vitals.

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 the exact calling protocol: it must follow audit_page, requires job_id, and should be re-invoked while status is running. It also names the alternative behavior it does not perform, so the when/when-not split is explicit.

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

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

With no annotations, the description carries the full burden, and it delivers on the highest-risk ambiguity: an empty list means no issues found, not a failed or incomplete call. It also discloses a restraint guarantee (does not invent unobserved issues). It omits auth/permission needs and any indication of result volume, 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?

Three short sentences, each earning its place: what it returns, what it will not fabricate, and how to read an empty result. The most decision-relevant content leads.

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 and no annotations, so the description must cover behavior and returns. It handles the return semantics well (categories plus empty-list meaning) for a one-param read tool, though it does not describe the shape of an individual finding or how to act on one.

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 single required crawl_id is undocumented in both schema and description. The description's 'from a finished crawl' context implicitly ties crawl_id to a prior crawl_site result, which is modest value, but it adds no format or sourcing detail.

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

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

Names a specific resource (cross-page findings) with a clear scope qualifier (from a finished crawl) and enumerates concrete finding types: duplicate titles, redirect chains, broken internal links, orphans. This distinguishes it from single-page siblings like audit_page and from crawl_site itself.

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 'from a finished crawl' implies usage timing but never states when to prefer this over audit_page (single page) or explain_finding (drill into a finding). No prerequisites or exclusions are given, 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?

With no annotations, the description carries the full burden and does disclose the two traits that matter most: it is non-mutating and scoped to a single account. It leaves 'recent spend' undefined (no time window or units), which is a minor but real gap for a read tool with no output schema.

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, all information-bearing, with the primary purpose front-loaded and the scoping caveats following. Nothing is 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 zero-parameter read tool with no output schema and no annotations, the description states what is returned and what is out of scope, which is everything an agent needs to call it correctly.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. No syntax or filtering options exist that would need explanation.

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

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

States a specific resource (credit balance) plus a second return (recent spend), so an agent knows exactly what it retrieves. It does not name any sibling to contrast against, but no sibling in the list plausibly overlaps with credits, so the risk of mis-selection is low.

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 clauses ('Does NOT change the balance', 'Does NOT show other accounts') establish clear scope boundaries and imply the when-not conditions. No alternative tool or prerequisite is named, so it stops short of explicit routing guidance.

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

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

With no annotations, the description carries the burden, and it does disclose useful behavior: an empty list is a valid result, and it won't fabricate links to unseen pages or alter copy. However, it never states that this is a read-only operation, whether results are cached, or whether the crawl must be in a finished state (only 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 tight sentences, front-loaded with the capability and then the scope exclusions. Every clause earns its place with no repetition.

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

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

No output schema and no annotations mean the description must cover return shape and safety, and it only partially does (empty-list case is covered, structure of a suggestion is not). For a one-parameter read tool this is adequate but leaves obvious gaps.

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

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

Schema coverage is 0% and there is a single required parameter, crawl_id, that the description never defines or tells you how to obtain (presumably from crawl_site). The phrase 'from a finished crawl' hints at the constraint but adds no real syntax or source 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+resource: internal-link suggestions derived from a finished crawl. This is unambiguous and no sibling tool overlaps with it, though it doesn't explicitly distinguish itself from adjacent crawl-output tools like get_crawl_issues.

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

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

There is no statement of when to reach for this tool versus alternatives (crawl_site, get_crawl_issues, audit_page). The description tells you what it produces but not the preconditions for calling it, such as needing a completed crawl first.

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

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

With no annotations present, the description carries the full burden and does add two useful scope/behavioral constraints: it excludes other users' sites and does not verify domains as a side effect. However, it omits further behavioral detail such as pagination, ordering, or the read-only nature beyond what 'list' implies.

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 the core purpose front-loaded and the scope caveats following immediately. Every sentence carries information and there is no filler.

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

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

For a simple single-parameter read tool with no output schema, the description covers purpose and two scope boundaries adequately. The notable gap is the undocumented include_archived parameter, which 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?

The schema has 0% description coverage for its single parameter, include_archived, so the description must compensate and does not mention it at all. An agent cannot tell from the description whether archived sites are included by default or how to change that.

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'), which is unambiguous. It does not explicitly differentiate from siblings, but no sibling overlaps with the listing purpose, so an agent can still place it 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 or when-not-to-use guidance and no named alternative. The usage ('list the account's sites') is only inferred from the verb, with no context about when an agent should reach for this versus other 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?

With no annotations, the description carries the full burden. It does disclose real behavioral traits — no submission side effects and the FAQPage edge-case — but omits return format, whether either parameter alone suffices, and any auth/rate-limit 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?

Three short sentences, front-loaded with the core purpose and followed by tightly scoped disclaimers. Each sentence carries distinct information with 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 tool with no output schema and 0 required parameters, the description should say more about expected inputs/outputs and how url vs json interact. The boundary clarifications are useful, but the calling contract for the two optional params is left unresolved.

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% (url documented as 'Public http(s) URL.', json undocumented), and the description says nothing about the two parameters, their relationship, or whether url and json are alternatives. It does not 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 names a specific verb (validate), resource (JSON-LD / schema.org markup), and the standard it checks against (Rich Results eligibility). It implicitly distinguishes itself from generate_schema through the verb, but never names siblings 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 exclusions ('does NOT submit to Google', 'does NOT measure whether rich results appear in search') usefully bound the tool and hint that other tools cover those needs, but no alternative tool is named and there is no explicit when-to-use condition or prerequisite.

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