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

Annotations already declare openWorldHint, non-idempotent, non-destructive. The description adds valuable context beyond them: it consumes one API credit per call and describes the returned artifact (scores plus prioritized fix checklist), which meaningfully informs invocation decisions.

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 sentences, front-loaded with purpose, then output, then cost/usage constraints. No filler; every sentence carries distinct 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?

With an output schema present, return values need not be detailed, and the description still summarizes them. It covers cost and scope trade-offs; the only gap is the absence of explicit sibling routing.

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 baseline is 3. The description adds meaning about scope behavior ('content'/'crawlability' run a narrower, faster scan), clarifying the trade-off beyond the schema's enumeration.

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 ('Scan one URL') scoped to AI-readiness, and the singular 'one URL' implicitly contrasts with site-wide siblings like start_site_analysis. An agent can tell what this does without opening the schema.

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

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

Provides a useful cost-driven guideline ('re-scan only after deploying a change') and explains the scope variants, but never names an alternative tool or states when to prefer start_site_analysis or a narrower scope. Usage is implied rather than routed.

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, so the safety profile is covered; the description adds genuinely new behavior beyond them: the error condition for an unknown report ID, the fact that it is free and consumes no credit, and rate-limit-adjacent polling guidance. These are operational traits an agent cannot infer from the annotations.

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

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

Five short sentences, front-loaded with purpose and return values before usage conditions and the sibling redirect. Nothing is redundant and no sentence could be dropped without losing a distinct fact.

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 and does so fully (status enum, progress percentage, suggested next tool). Combined with error behavior and cost disclosure, 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?

Schema description coverage is 100% for the single report_id parameter, so the schema already carries the syntax. The description restates the provenance (returned by analyze_website) and adds the unknown-ID error behavior, but no format or constraint detail beyond the schema — 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 ('check the progress of one page scan by report ID') and enumerates the possible statuses (queued, processing, complete, failed) plus what else comes back. It explicitly distinguishes itself from the whole-site sibling by naming get_fix_plan as the alternative.

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

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

Gives concrete triggers ('when analyze_website returned a report ID before the scan finished, or after you started a scan with wait=false'), an explicit alternative for a different scenario (start_site_analysis → get_fix_plan), and a polling cadence instruction ('every few seconds, not in a tight loop'). This is exactly the when/when-not/alternative coverage the dimension asks for.

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), and the description adds meaningful context beyond them: unmeasured data comes back as TODO rather than a guess, and the call is free (no credit). That is exactly the kind of caveat annotations can't express.

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 core purpose, then the three kinds, then the TODO caveat, the exclusivity constraint, and the cost note. Dense but every sentence carries information; minor nesting in the kind list is the only drag.

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 an output schema present, return values need not be described, and the description still covers artifact variants, TODO placeholders, the pre-commit check, parameter exclusivity, and cost. Referencing a needsHumanInput tool absent from the sibling list is the one loose end.

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 parameter definitions are already documented, but the description adds a constraint the schema does not enforce: 'Pass exactly one of report_id or domain_id', plus the report=page-scoped / domain=site-scoped mapping implied by the kinds.

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 file that fixes a deterministic finding') and enumerates the three artifact kinds with a short gloss for each, so an agent can tell exactly what it produces. It is clearly distinguishable from siblings like get_fix_plan or get_findings.

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 real usage context: use it for deterministic findings, check needsHumanInput before committing, and pass exactly one of report_id or domain_id. It doesn't explicitly name an alternative tool or a when-not-to-use condition, so it falls short of a 5.

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

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

Annotations already cover readOnly/idempotent/non-destructive, but the description adds context they cannot express: the cost model ('Free: does not use a credit'), the stability guarantee of ids across re-scans, and the per-finding 'apply' vs propose policy governing whether an agent may act unattended. These are material behavioral traits for an agent deciding whether and how often to call it.

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

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

Dense and largely waste-free, with the operating constraint and alternatives present, but it opens with a definitional sentence about findings rather than the action itself and runs long in a single block. Nothing is redundant enough to cut outright, though it could be split for scanability.

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

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

For a read-only, two-parameter list tool with a full output schema, the description supplies everything else an agent needs: the error case, the cost implication, and the follow-up tools. Return value details are correctly left to the 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 coverage is 100%, so the baseline is 3, but the description adds the mutual-exclusivity rule and its failure mode, which the schema only hints at with 'Omit if you pass...'. It clarifies which source each id maps to (one page vs latest site analysis) in a way the schema field descriptions do not fully frame.

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 ('findings'), defines it concretely ('the fix list keyed by rule'), and explicitly separates it from the sibling get_report ('Use get_report instead if you only need scores'). An agent can distinguish this from get_report, verify_findings and get_fix_plan 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?

It states the exact invocation constraint ('Pass exactly one of report_id ... or domain_id ... otherwise it returns an error'), names a substitution for a neighboring need (get_report for scores), and lists the downstream tools that consume the returned ids (verify_findings, update_finding, get_artifact). This is explicit when-to-use and when-not-to-use 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?

Goes well beyond the annotations (which only declare read-only/idempotent/non-destructive) by disclosing cost ('Free: does not use a credit') and the required auth scope ('domain:read'). Both are operationally decisive facts an agent cannot get from the 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?

Two sentences, no filler, and the highest-value information (what you get, then how to select the run, then cost/scope) is ordered by importance.

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 output schema covers the return structure, so the description only needs selection logic, cost, and scope — all three are present. Nothing an agent needs to invoke this 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 coverage is 100%, so the per-parameter docs already carry the baseline. The description adds a real constraint the schema does not encode — 'Pass exactly one of domain_id or site_analysis_id' — since neither parameter is marked required and no oneOf is declared.

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: 'Read the ranked, site-wide fix plan from a domain's latest site analysis.' It even previews the record shape (pages affected, fix instructions, URLs to verify), which separates it cleanly from siblings like get_findings or get_report.

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

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

Gives a clear selection rule for the two entry points ('domain_id (latest run)' vs 'site_analysis_id (a specific run)'), plus prerequisite scope. It does not, however, say when to prefer get_findings or get_report over this tool, so routing between siblings 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 cover read-only/idempotent/closed-world safety, but the description adds non-obvious behavior: never rescans, returns a snapshot of the page as scanned, errors on unknown or cross-account IDs, and consumes no credit.

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 core action and payload, then layers usage, staleness semantics, error behavior, and cost in tight successive clauses 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?

An output schema exists, so return-shape explanation is unnecessary; the description still covers the snapshot semantics, error conditions, and free-of-credit cost that an agent needs to call and interpret 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?

Schema coverage is 100% and the report_id parameter already documents its origin tools and UUID format, so the description's provenance remarks largely restate the schema. No additional syntax or constraint detail is added, 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?

States a specific verb (Read) and resource (stored page report), and enumerates the payload (scores, prioritized fix checklist, plan-locked fix note). It clearly distinguishes itself from the analysis siblings by emphasizing stored/saved data.

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

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

Explicitly scopes use to when a report ID is already in hand and names the three tools that produce one (analyze_website, check_status, list_reports). It also names the alternative path — call analyze_website to see changes — so the agent can route correctly.

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 covered. The description adds value beyond them by telling the agent what information is returned and when in a workflow to invoke it, which is the useful behavioral context for a no-arg read 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?

Two short sentences with zero filler: the first states what is returned, the second states when to call it. The most actionable content (what you get) is front-loaded.

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

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

For a zero-parameter, read-only, non-destructive lookup with no output schema, the description covers what the agent needs: the returned fields and the workflow moment to call it. Nothing material 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?

The tool takes zero parameters and the schema has 100% description coverage, so the baseline of 4 applies. The description correctly does not invent parameter semantics that do not exist.

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') and enumerates the exact resources returned: the plan, API credits used and remaining, and the billing period. No sibling in the list (analyze_website, get_report, list_domains, etc.) overlaps with billing/usage, so no differentiation is strictly needed, but the description never names or rules out an alternative.

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 proactive trigger: 'Call before a batch of scans.' That is real when-to-use guidance rather than a generic 'use this to check usage.' It stops short of 5 because it names no alternatives or when-not-to-call condition, though none of the siblings plausibly compete.

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 it read-only, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds a genuinely non-structured behavior constraint: it requires an API key with the 'domain:read' scope. Pagination or result-size behavior is not mentioned, 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, zero waste, front-loaded with the resource and its output followed by the one prerequisite. 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?

An output schema exists, so return values need no explanation. Between the description and annotations the agent knows what the tool returns, its safety profile, the required auth scope, and where the result feeds next. Nothing needed to invoke 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?

The tool takes zero parameters, so there is nothing for the description to compensate for; baseline for a parameterless tool is 4. No parameter syntax is described, and none is needed.

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 the account's monitored domains') and even names what it returns ('their IDs'). It also names the sibling that consumes this data (get_fix_plan), letting an agent place it in a workflow without opening the schema.

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

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

Explicitly frames the use case: obtain domain IDs 'for use with get_fix_plan'. That is clear chaining guidance rather than implied usage, but there is no when-not guidance or statement about alternatives (e.g. versus other listing 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds value on top: the operation is free and consumes no credit, results are paginated up to 100 with a page count at the top of output, and the empty result returns 'No reports found.' None of this is in the structured data.

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 core action and ordering, then layers alternatives, cost, filtering, pagination and empty-state in tight sentences. Every sentence carries distinct, actionable 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, so the description fully carries the return contract: entry fields (ID, URL, score, status, creation time), pagination behavior, and the empty-state string. Nothing an agent needs to call or interpret 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 coverage is 100%, so baseline is 3, but the description adds workflow-level meaning the schema lacks: filtering by URL or status, the up-to-100 page size, and the read-the-page-count-then-request-next-page loop. This meaningfully exceeds what the raw parameter docs 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 and resource ('List the page reports this account has generated') plus ordering ('newest first'), and enumerates the fields each entry contains. An agent can distinguish it from get_report and get_findings 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 names the alternatives and the selecting conditions: use it to find a report ID for get_report/get_findings, or to check already-scanned pages before spending a credit on analyze_website. This is exactly the when/when-not/which-sibling guidance the dimension rewards.

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?

Adds substantial context beyond the annotations: one credit per page, the budget cap interacting with remaining credits, a 25-page OAuth ceiling that max_pages overrides, immediate (async) return, and the required 'site:analyze' scope for API-key auth. Annotations only cover the safety profile; the description carries the cost, auth, and limit behavior an agent needs.

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?

Purpose is front-loaded and most sentences carry real information, but the middle clause about the plan cap and credits is compressed to the point of ambiguity ('the smaller wins'), costing some readability.

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?

Cost, auth scope, page cap, and async return are all covered, which is the hard part for a bulk-scan starter. However, with no output schema the description never says what it returns (e.g., a run identifier) or how to follow up via check_status, leaving the post-call workflow unaddressed.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds rationale for max_pages (it lifts the OAuth 25-page default cap) but says nothing about include/exclude, whose semantics and ordering live entirely in the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Start a site-wide analysis') plus the scope that separates it from a single-page tool: it picks its own pages rather than accepting a URL list. An agent can identify this as the site-wide crawl variant without opening the schema.

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

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

Explains the page-selection heuristic (homepage first, then high-coverage sections) and the cost implication, which tells the agent when this is worth calling. It gives clear context but does not explicitly name a sibling like analyze_website as the single-page alternative or state when not to use it.

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

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

Annotations give the safety profile (not read-only, idempotent, non-destructive), and the description goes well beyond them: it states the side effect of 'ignored' (silences a finding), the rollback semantics of 'open', the hard restriction that 'verified' is unreachable here, and that no credit is consumed. That is exactly the extra context annotations cannot carry.

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 intent, then the status semantics, then the exclusion and the cost detail. Every clause conveys a distinct operational fact with no 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 4-parameter mutation tool with no output schema, the description covers the status lifecycle, the reason requirement, and the alternative path for verification. It is slightly silent on what a successful call returns or how 'ignored_until' interacts with undo, though the schema covers the latter.

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 schema already documents status values, the conditional reason requirement, and finding_id provenance, so the description is largely restating them. It adds only the mild clarification that 'open' undoes either prior state, which the schema also implies. 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 frames the operation functionally ('Remember a decision so a later session does not redo it') and enumerates the three status values it can set, which makes the resource (a finding's status) inferable but never states it directly as 'update a finding.' It does cleanly separate itself from verify_findings, so 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?

Gives explicit per-value guidance: 'fixed_pending' for changes not yet deployed, 'ignored' to silence, 'open' to undo, plus the exclusion 'You cannot set verified: that is earned by calling verify_findings.' The cost note ('Free: does not use a credit') further arms the agent's decision between this and sibling 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 annotations present, the description still adds meaningful context: exactly one live page fetch per check, no analysis performed, and no credit consumed — cost and side-effect information the annotations do not convey. It also names the return vocabulary. It stops short of describing rate limits or failure modes of the live fetch, keeping it out of 5 territory.

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 purpose, then the cost/behavioral caveat, then the routing advice and parameter rule. No filler and nothing repeated from the schema.

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?

Output schema covers the return shape and annotations cover the safety profile, so the description only needs to add the non-obvious bits — plan gating, zero-credit behavior, and the exactly-one-identifier rule — which it does. Nothing an agent needs to invoke this 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 coverage is 100%, so per-parameter meaning is already documented. The description adds a genuine constraint the schema lacks: 'Pass exactly one of report_id, domain_id or site_analysis_id' — a mutual-exclusion rule not encoded as oneOf. It also clarifies finding_ids is optional.

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 (re-check findings after a fix) and immediately scopes it: one live page fetch, no analysis, no credit. The three possible verdicts (verified, still_failing, unverifiable) make the outcome concrete, so an agent can distinguish it from analyze_website at a glance.

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 alternative and the condition that selects this tool: 'Use this instead of re-running analyze_website.' It also adds a practical gating condition (included with Pro and Agency), which tells the agent when the call will even succeed.

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