pageaudit

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

The description supplies useful behavioral context (auth requirements, that acknowledgement preserves evidence and does not retract a sent notice). However, it explicitly states "Repetition is idempotent," which directly contradicts the annotation idempotentHint=false, making the safety/behavior profile self-inconsistent.

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 consecutive sentences ("Preserve the event and its evidence. Preserve the event and observation.") are near-duplicative and waste space, and the idempotency sentence conflicts with annotations. The auth preamble is front-loaded well, but overall the text is redundant and muddled rather than tight.

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 mutation tool with no output schema, the description does cover auth prerequisites and some post-conditions, which is more than the annotations alone provide. Still missing are clear consequences of acknowledgement, return behavior, and any resolution of the idempotency contradiction it introduces.

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 100% schema description coverage, the schema already documents both parameters (id sourced from list_tabs, positive history event number). The description adds nothing about parameter meaning, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ("Acknowledge an expected event") and clarifies semantics like suppression of the notice. It does not, however, name or differentiate itself from nearby siblings such as domain_history or apply_domain_alerts, so the agent must infer the boundary.

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

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

There is implied usage context ("expected event", "suppress its notice only if sending has not started") that hints at when acknowledgement is appropriate. But no alternative tool or explicit when-not guidance is offered, so routing between this and related history/alert tools 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=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior: a 409 site_limit error code and the note that the guest audit workspace stays separate. However, 'No site count limit' directly undercuts 'An account holds up to 1,000 sites', making the actual constraint ambiguous.

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?

Short overall, but one of the three sentences ('No site count limit') contradicts the next sentence's 1,000-site cap, so a third of the payload is confusing rather than informative. The useful info (limit, error code, workspace isolation) is not front-loaded cleanly.

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 create tool with a full annotation set and 100% schema coverage, the essentials are present. The account-limit story is self-contradictory and there is no output/return description, leaving a noticeable gap despite the low overall 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?

Only one parameter and schema description coverage is 100%, so the schema already documents url as a public HTTP(S) URL without credentials. The description repeats 'site' without adding format, validation, or normalization details, so 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 (Add) and resource (a site) to the account, which is immediately distinguishable from list_sites and get_site by verb. It stops short of explicitly contrasting with siblings, but the action is unambiguous.

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

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

There is no guidance on when to use this versus alternatives (e.g., audit_site, audit_url, list_sites), no prerequisites, and no mention of what happens on duplicate URLs. The agent gets an action but no decision 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real value: it clarifies that reads never invoke the search engine (no external calls or quota impact) and spells out the trend semantics (up/down/same/new/lost) that the annotations cannot 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-loaded with the read scope, followed by a key behavioral caveat and a compact definition of the trend values. Every sentence carries information; the trend clause is dense but earns its place by defining return semantics not available elsewhere.

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

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

There is no output schema, so the description must characterize the return, and it does: plan, saved searches, last runs, and per-search trend values. Combined with annotations covering safety and a fully documented parameter, an agent has enough to call it correctly, though pagination or result shape is not addressed.

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

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

Schema coverage is 100% with a single documented 'id' parameter, so the schema does the heavy lifting. The description adds no syntax, format, or constraint detail about the id beyond what the schema already provides. 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 clear verb (Read) and enumerates the resource contents: plan, saved searches, last runs, and position trend. An agent knows exactly what data this returns. It doesn't explicitly differentiate itself from siblings like ai_search_visibility or save_ai_search_queries, but the scope is unambiguous.

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

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

No when-to-use guidance and no named alternatives. The description explains what is returned but never states the condition that selects this tool over ai_search_visibility or save_ai_search_queries. The 'reads never call the search engine' note is behavioral, not a usage selector.

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 annotations: per-query credit cost (USD 0.00075 per indexed result), weekly vs watch-package rate limits, the one-index-check-plus-one-search-per-query model, and the flag that titles/snippets are third-party data. It does not explain why readOnlyHint is false despite the 'Check' framing, but the metered-run language largely accounts for 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?

Front-loaded and information-dense, but the omitted-queries fallback is stated twice in near-identical wording ('Uses the saved searches or the ones the page suggests when queries is omitted' then 'Send {} to use the saved searches, or the searches the page title and H1 suggest'). That redundancy costs a point.

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

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

With no output schema, the description carries the return-shape burden and does so: positions, competing sites, plain recommendations. Combined with cost and quota disclosures and full schema coverage, an agent has enough to call it correctly; only the absence of explicit alternative-tool routing is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by defining the defaulting behavior when queries is omitted versus supplied, which is semantic information the field description ('Optional. One to ten searches') does not carry.

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

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

States a specific verb and resource: it checks whether a page appears in AI search for each target query, at what position, who outranks it, plus recommendations. This is clearly distinguishable from siblings like ai_search_history (past runs) and save_ai_search_queries (managing query sets).

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 query-input branches precisely: omit queries to fall back to saved searches or title/H1-suggested searches, or pass queries to choose explicitly. It also discloses when the tool is usable in practice via weekly/daily run and search quotas, but never names a sibling alternative for the full visibility-history use case.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds the 'self-describing index' trait, which hints at the return format, but does not disclose auth needs, rate limits, or what the index actually contains.

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

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

A single front-loaded sentence with no filler. It is appropriately sized for a zero-parameter tool, though the parenthetical is slightly redundant with the main clause.

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, no-output-schema tool whose annotations cover safety, the description is minimally adequate. It does not explain what the self-describing index returns or how it relates to other discovery siblings, leaving the agent to guess at the output structure.

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. The description correctly implies a no-input discovery call and adds nothing misleading about parameters.

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 ('Discovers') and resource ('the whole PageAudit API'), and the parenthetical 'self-describing index' clarifies the mechanism. It does not, however, differentiate itself from sibling discovery tools like list_tools or get_tool, leaving a small ambiguity.

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

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

There is no when-to-use guidance, no conditions, and no named alternatives. The agent must infer that this is a discovery entry point, but nothing tells it when to prefer this over list_tools or get_tool.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, openWorldHint=false, so the mutation profile is known. The description adds genuinely non-structured behavior: required auth context, server-side revalidation of account/organization/revisions, and the stale-preview no-op, which tells the agent the call can silently do nothing.

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?

Roughly seven short sentences with the critical auth/precondition facts front-loaded, but the sentence "A stale preview changes nothing" is repeated verbatim, which is pure waste and suggests the text was assembled without editing.

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 destructive, non-idempotent write with no output schema, the description covers auth, prerequisites, server-side validation, and the dedup cap — enough for an agent to call it correctly. It is slightly silent on the success outcome (what the applied alerts actually produce for the user), but that gap is minor.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description adds deduplication semantics not in the schema: repeated registrable domains count once, and selection is capped at 25 saved pages. That extra rule meaningfully changes how the agent constructs the tabs array.

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 ("Apply") on a specific resource (the reviewed domain-alert selection) and clearly positions itself downstream of preview_domain_alerts. It is somewhat abstract about what the end result is (renewal notices at lead_days), but the agent can distinguish it from the sibling preview tool without opening 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 a strong precondition ("Requires the preview from preview_domain_alerts") plus the write-auth prerequisites (account session, X-Organization-Id, CSRF), which effectively routes the agent to the preview tool first. It does not state any when-not-to-use case beyond the stale-preview no-op, so it stops short of explicit exclusions.

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

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

With annotations present, the description adds real behavioral context beyond them: the one-hour caching window returning a stored sample (with cached_at), that out-of-host URLs are counted but never requested, and that a re-request within the hour avoids spending the allowance. This is valuable disclosure not covered by the hints.

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

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

The text is marred by verbatim duplication: 'URLs of another host are counted, never requested.' appears twice, and the caching sentence about the stored sample appears twice (once with cached_at). This wastes space and undermines front-loading.

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 covers scope, sample size, caching, and allowance behavior reasonably well, but it never sketches the shape of the returned audit result, leaving the return surface largely unspecified for a tool with no output schema.

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

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

Schema description coverage is 100%, so url, lang, and guest_token are already documented in the schema. The description adds no parameter-level meaning beyond that, so baseline 3 applies.

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

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

The description states a specific verb and resource with clear scope: 'Check the first 20 URLs of a site's sitemap' and enumerates what is checked (status, redirects, robots.txt, noindex, canonical, titles). It implicitly distinguishes from audit_url (single URL) via 'sitemap', 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?

It conveys context ('The free sample of the SEO audit', 'Free, without an account'), which implies when it is appropriate, but there is no explicit when-to-use/when-not or routing to audit_url/check_domain for related needs.

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 beyond annotations with concrete behavioral facts: no saved tab is created, a blocked target returns HTTP 502 with target_blocked, and the report does not certify security or accessibility. These error and scope details are not derivable from readOnlyHint/openWorldHint/destructiveHint. It still doesn't clarify why readOnlyHint=false despite no saved tab (e.g. quota or audit record writes).

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

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

The behavioral and error details are front-loaded and useful, but the trailing sentences ('This is the product for agents. The free alternative: a person signs in with an account to get the trial.') are marketing-flavored and loosely related to tool selection, adding noise to an otherwise compact description.

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 reasonably ('evidence, limits and suggested changes') plus a documented failure mode (502/target_blocked). Scope disclaimers round it out, though return shape specifics remain thin.

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

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

Schema description coverage is 100%, so all three parameters (url, guest_token, compare_with) are already documented in the schema. The description adds no syntax or format detail beyond that, making 3 the appropriate 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?

The description gives a concrete verb ('Check') and enumerates the audited resources (search metadata, crawl access, structured data, discovery files). It distinguishes itself from persistence-oriented siblings by stating it works 'without creating a saved tab', though it never names the closest sibling audit_site 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?

'This is the product for agents. The free alternative: a person signs in with an account to get the trial' addresses audience/eligibility but not when to choose this over audit_site or run_tab. The 'without creating a saved tab' clause implies a no-persistence use case, but no explicit when/when-not guidance or named alternatives are provided.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description genuinely adds auth context (account session, X-Organization-Id, CSRF for writes) and the preservation rule for completed evidence, but a large share of the text concerns scanning behavior, deadlines, and report expiry that are irrelevant to a cancellation call.

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

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

The content arrives as one undifferentiated run-on covering authentication, quotas, scanner internals, deadlines, and report TTLs. The actual purpose appears only in the second sentence, so the definition is not front-loaded and carries several sentences with no bearing on cancellation.

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 destructive, no-output-schema tool, the description omits what actually happens to an in-progress review on cancel, error conditions, or reversibility, while spending most of its length on unrelated scan/expiry facts. It is verbose in the wrong places and thin where the agent needs certainty.

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 single 'id' parameter is documented as "Owned tab ID from list_tabs". The description adds no meaning about 'id' and instead discusses account/organization/origin scoping, so the baseline 3 applies with the schema doing all 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?

The sentence "Cancel the current TLS review and preserve completed evidence" states a specific verb (cancel) and resource (current TLS review), so the core action is identifiable. However, it never distinguishes itself from the sibling tools 'connection_review' and 'review_connection', and the purpose is buried behind an opening sentence about session/CSRF requirements.

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 offers no guidance on when to cancel versus letting a review finish, nor any alternatives. The quota sentences ("three starts per UTC day", "current domain monitoring rights") describe requirements for STARTING a review, not for canceling, so they give the agent no actionable selection criteria for this tool.

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

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

Annotations only declare safety hints, and the description adds substantial behavior beyond them: one-hour result caching with a cached_at field, no authentication required, the Cloudflare IP-verification caveat that can make a bot-trust rule behave differently, and the definition of a stale sitemap (>30 days lastmod). This is exactly the 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?

The core is front-loaded, but the text is visibly redundant: the crawler list is enumerated twice and the one-hour caching behavior is stated twice ('returns the stored result' appears in two separate sentences). Trimming the repeats would roughly halve the length 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?

With no output schema, the description carries the return-value burden and does so: it explains that results are per-crawler status codes/challenges, plus newest sitemap lastmod date and Cloudflare presence. For a one-parameter tool with annotations covering safety, 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?

Only one parameter and schema description coverage is 100%, so the schema already documents 'the page to check'. The description implies the URL is fetched live as multiple user agents but adds no format, normalization or subpath guidance, so baseline 3 applies.

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

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

The first sentence names a specific action (request a page as named crawler user agents) and a specific output (who gets a 403/429/firewall challenge), which is a distinct capability from the audit_*/check_domain siblings. An agent can tell what it gets back 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 gives context that shapes use (free, no account needed, repeated calls within an hour return the cached result), which implicitly says 'safe to call repeatedly'. However it never states when to prefer this over audit_url, audit_site or check_domain, so sibling selection 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 annotations only flagging readOnly=false, openWorld=true, idempotent=false, destructive=false, the description adds genuinely non-derivable behavior: fresh public data is reused, failed or partial queries preserve the last complete observation and its date, and there is a hard budget of 100 cold page reads per owner per UTC day. These caching, failure, and rate-limit semantics go well beyond the annotations. Auth/permission requirements and expected latency are still 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?

The operation's scope is front-loaded well and the rate limit appropriately closes the description. But "Reuses fresh public data. Reuse fresh observations." is near-duplicative filler, and the telegraphic fragment style makes the subject of the first sentence ambiguous (what exactly is being refreshed?).

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 mutating, open-world refresh with no output schema and only two of four annotation hints carrying detail, the description covers reuse, failure preservation, and throttling, which is decent. It still omits what the result conveys, why a tab `id` is required, and how this relates to `domain_status`, leaving meaningful gaps for an agent choosing between them.

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%: `id` is documented in the schema as an owned tab ID from list_tabs, while `guest_token` is undocumented there and gets no explanation in the description. The description mentions "per owner" but never connects that to any parameter, 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 verb ("Refresh") and enumerates the resource facets it re-collects: registration, contacts, TLS, DNS, mail policies, certificate issuance, and a DNS/TLS sample. An agent can form a concrete picture of the operation. However, it never distinguishes itself from the sibling `domain_status` (or `get_audit`), so the reader must guess how 'check' differs from 'status'.

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

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

There is no explicit when-to-use or when-not-to-use statement, and no sibling is named as an alternative. The clues about reuse ("Reuses fresh public data") imply it is safe to re-invoke, but the agent gets no routing guidance versus `domain_status`, `audit_url`, or `list_tabs`.

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

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

Beyond the annotations it discloses auth prerequisites (account session, X-Organization-Id, CSRF for writes), conflict handling (a conflicting revision returns 409), preservation of omitted settings, and notification behavior for rotation vs alias changes. One nuance: it says 'an identical retry is idempotent' while annotations declare idempotentHint=false; this reads as a refinement (guarded by the revision field) rather than a flat misstatement, and the destructiveHint=true annotation is consistent with a settings-overwriting write.

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

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

Nearly every sentence carries factual load (auth, idempotency, 409, preservation), so there is little filler. However, it is a chain of telegraphic fragments that opens with prerequisites instead of the purpose, so the reader must assemble the tool's function from the name and scattered clauses.

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

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

For a destructive, nested-object, no-output-schema tool this covers the essentials an agent needs: auth requirements, revision/conflict semantics, partial-update behavior, and the scope exclusions. It would be fully complete if it resolved the manual_expires_on discrepancy and clarified what the write replaces.

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 id, revision, and the nested dns object, making 3 the baseline. The description restates the dns requirements and adds 'omitted settings are preserved,' but it also references 'manual_expires_on,' a setting that does not appear anywhere in the input schema, which introduces confusion rather than meaning.

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 concrete verb+resource (set DKIM selectors and IP-rotation expectation for a domain's DNS) and draws boundaries against siblings by saying it 'does not discover selectors, enable monitoring or authenticate sent messages,' which implicitly separates it from configure_domain_monitor and domain-verification tools. It is clear, though the core purpose is threaded between prerequisites and constraints rather than stated up front.

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

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

It gives explicit conditional guidance: 'Send manual_expires_on, dns, or both. Omitted settings are preserved,' and states the DNS payload 'requires both selectors and rotating_addresses.' It also lists what the tool does not do. It stops short of naming a specific alternative tool to use instead, so it is context-rich but not a full when/when-not routing table.

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

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

Annotations already declare this a destructive, idempotent write, but the description adds real behavioral context beyond them: it requires an account session, X-Organization-Id, and CSRF for writes, explains that maintenance pauses notices while collection continues, notes HTTP gets DNS checks only, and instructs verifying enabled/no-suspension/next_check_at after saving.

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

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

It is front-loaded with the auth prerequisite, which is good, but several fragments ('Add only the tab's origin', 'HTTP receives DNS checks only') are dense and hard to parse without prior context, and the seven short sentences read as telegraphic rather than well-structured prose.

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 destructive mutation with no output schema, it covers auth requirements, mode semantics, and even a post-save verification checklist, so an agent has almost everything needed. The remaining gap is the lack of explicit routing to sibling tools for related DNS or alert configuration.

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 id, revision, enabled and maintenance_until with format and default guidance. The description adds no parameter-level syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

The description states three concrete operations on a specific resource: enable monitoring, stop it, or pause notices for maintenance. An agent can distinguish this from siblings like configure_domain_dns or domain_status by scope, though it never names those 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?

It gives clear selection context between the modes (enable/stop vs. maintenance pause) and adds scoping rules such as counting a registry domain once per account and adding only the tab's origin. It does not name an alternative tool or state explicit exclusions, 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?

Beyond the annotations (readOnly, idempotent, openWorld=false, destructive=false), the description discloses a great deal: one review per account/org/origin/UTC-day, three starts per day, retries returning the same review, scanner IP sampling, three stages, a 170-second deadline, that partial results do not establish safety, and a 26-hour expiry. This is exactly the behavioral 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?

The text is dense with distinct facts and every sentence carries information, with no filler. It is slightly back-loaded: the auth/CSRF preamble leads rather than the core "read the review" purpose, which would be better 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 one-parameter, read-only tool with no output schema, the description covers timing, idempotency, expiry and results caveats thoroughly. Its only real omission is clarifying the relationship to the sibling review_connection, whose name is nearly identical.

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%, with 'id' documented in-schema as an owned tab ID from list_tabs. The description adds no additional parameter meaning, which is the expected baseline when the schema already 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?

The description states a specific verb and resource: "Read today's private TLS review without starting a scan." That is clear and actionable. However, it does not differentiate itself from the very close sibling review_connection, so an agent cannot tell from the text which of the two to pick.

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 "without starting a scan" and the note that "GET never starts a scan", which contrasts with a starting path. But no alternative tool (review_connection, cancel_connection_review) is named, and there are no explicit when/when-not conditions routing the agent between siblings.

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

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

Annotations set readOnlyHint=false, openWorldHint=true, etc., but the description adds crucial behavioral detail: it is a read-only consent flow despite the mutation hint, requires a browser redirect, has a five-minute expiry, single-use callback, and binding to account and site. These are essential operational traits not covered by annotations, making this highly transparent.

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

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

The description is a series of six short sentences that front-load the critical action ('Start read-only Google consent') and then provide necessary constraints. It is efficient with no obvious redundancy, though it could be slightly more structured by grouping prerequisites and 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?

Given no output schema and annotations that only signal open-world, non-idempotent, non-destructive behavior, the description adequately covers the consent flow's required steps and temporal constraints. It could benefit from mentioning what happens after consent (e.g., connection saved) or error conditions, but it is largely complete for an agent to invoke 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%, so the schema already documents parameters (id, property, language). The description mentions 'account' and 'site', which loosely correspond to id and property, but adds no syntax, format, or meaning beyond what the schema provides. 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 opens with 'Start read-only Google consent', which indicates the operation begins a consent flow for Google Search Console. However, it does not explicitly name the resource being connected (Search Console) or the resulting action (connecting a property), making it less distinct from siblings like 'disconnect_search_console' or 'sync_search_console'. The purpose is implied but lacks the specific verb+resource precision needed for a 4 or 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 description implies usage by stating prerequisites (account owner must follow redirect) and constraints (consent expires, callback single-use), but it does not explicitly say when to use this tool versus alternatives like 'sync_search_console' or 'disconnect_search_console'. The guidance is inferable from context but not clearly delineated.

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: a per-network rate limit of one message per 10 seconds with queuing (not an error) on overage, delivery by e-mail with `email` as reply address, a 32 KiB JSON cap and a 2 MB audio cap, and a two-minute browser recording limit. The annotations (readOnlyHint=false, non-idempotent, non-destructive) cover the safety profile, and the description enriches it well; response/confirmation behavior is the only notable omission.

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 purpose, then mechanics, with no filler sentences — every claim (limits, formats, delivery) earns its place given an 18-parameter tool. The sentences are dense and stacked with parentheticals, which slightly hurts readability, but there is 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 an 18-parameter, multi-mode write tool with no output schema, the description covers delivery path, size/rate constraints, and the conditional field groups that an agent must get right. It stops short of describing what a successful response contains, but the critical invocation guidance is present.

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 already 94%, so the baseline is 3, but the description adds genuine cross-parameter meaning: `tipo` activates the proposal fields, `espaco` must be placement ids from `GET /api/partners`, `orcamento` has different enum sets for advertising vs consulting, and `prefer_whatsapp` requires `whatsapp`. This is meaningful semantics the schema does not express on its own.

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?

Opens with a specific verb and audience ('Write to the people behind the product') and immediately enumerates the supported intents (question, sponsorship, partnership, advertising proposal). No sibling tool in the list is remotely similar, so differentiation is trivially satisfied and the purpose is unmistakable.

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 routing between the question and proposal paths via `tipo`, notes that `tipo` 'turns on the fields below', and covers the split between JSON and multipart voice submission. It does not state when not to use this tool or name any alternative, but the usage context is clear enough to invoke 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 this is a non-read-only, non-destructive, non-idempotent creation, and the description is consistent with that. It adds genuinely useful behavior beyond the annotations: the token is a credential-like identity whose loss affects all tabs and audits tied to it, which is the key operational warning 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?

Two short sentences, front-loaded with the action and immediately followed by the one instruction that matters (keep the token). Every clause 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 zero-parameter, no-output-schema tool the description covers what is created, its format, and why it must be retained. It leaves minor gaps such as whether multiple guests may exist, token lifetime, or whether the token can be re-fetched later.

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 per the baseline there is nothing for the description to disambiguate. The mention of the pa_… token format is extra information about the output, not a 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?

Specific verb (Creates) plus specific resource (a guest token, with the pa_… prefix) and scope (for the tab workspace), which distinguishes it from create_tab and add_site. It stops short of naming a sibling or contrasting itself with one.

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 description indicates the token belongs to the tab workspace and anchors tabs and audits, so an agent can infer when a guest identity is needed. There is no explicit when-to-use versus alternatives, no prerequisites, and no statement of when not to call 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 already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The one behavioral sentence about queue_audit duplicates the schema's parameter description verbatim in substance, adding nothing beyond what structured data already provides (e.g., no mention of tab lifecycle, persistence, or why a guest token is required).

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 no filler and the core action front-loaded. It is efficiently sized, though the second sentence spends real estate restating 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?

For a mutating tool with a required undocumented credential (guest_token), no output schema, and several closely related tab siblings, the description leaves key questions unanswered: what a tab is, whether it persists, and how it relates to run_tab/watch_tab. Annotations cover the safety profile, but the operational framing is thin.

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 75%, so most parameters are already documented, and the baseline is 3. The description only echoes queue_audit behavior already stated in the schema and adds nothing about url, alias, or the undocumented guest_token, which is a required parameter with no description anywhere.

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 says 'Opens a saved URL', which is a vague verb that does not clearly convey that a persistent tab record is being created. It never distinguishes this tool from siblings like run_tab, watch_tab, or list_tabs, so an agent must guess which tab tool actually creates the entry.

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 only usage hint is the queue_audit=false case, which just restates a parameter default. There is no guidance on when to use create_tab versus run_tab or watch_tab, and no mention of prerequisites such as the required guest_token.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds real value beyond them: the last good sample is retained and remains available, and an in-flight callback or collection cannot reconnect the site. That clarifies the blast radius and the irreversibility semantics rather than restating 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?

The destructive action is front-loaded, but 'Keep the last good sample. The last good sample stays available.' is a redundant restatement of the same fact, wasting a sentence in a four-sentence description.

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 destructive one-parameter tool with no output schema, the description covers effect (credential removal, collection stops), data retention, and the fact that in-flight work cannot re-establish the connection. Prerequisites and post-state recovery path are the only real omissions.

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

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

Schema description coverage is 100% and the single 'id' parameter is documented in the schema as coming from list_sites or add_site, so the schema carries the load. The description adds nothing about the parameter, which is the expected baseline here.

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 ('Remove the local Google credential and stop collection') and is unambiguously the inverse of connect_search_console / sync_search_console among siblings. An agent can tell what it 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?

Usage is implied by the verb (disconnect a site that is currently connected), but there is no explicit when-to-use guidance, no prerequisite such as 'site must currently be connected', and no named alternative for re-enabling collection (connect_search_console).

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, and the description still adds substantive behavior: required session, X-Organization-Id and CSRF, a 50-item page cap, the cursor idiom, and a dedup rule ('Repeated observations do not duplicate a notice'). It also flags interpretation caveats (issuance doesn't prove installation, DNS records don't prove authentication). Most of the remaining text is data semantics rather than tool behavior, which keeps it at 4 rather than 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?

The description is an unstructured run-on of domain-semantics statements with no paragraphing or priority order; the actual purpose appears only after the auth prerequisites. Several sentences are cryptic ('Send the last event number as before', 'A first observed risk is an initial incident') and not obviously actionable for invoking the tool.

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

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

For a read-only tool with full annotations and no output schema, the description covers auth, page limit, pagination, dedup, and the meaning of the incident kinds an agent will see. It is reasonably complete, though it never sketches the returned event structure, which a no-output-schema tool could benefit from.

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 'id' and 'before' are already documented and the baseline would be 3. The description earns above baseline by explaining how to drive 'before' operationally (send the last event number to get the next page) and by stating the page-size cap, which the schema 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?

The second sentence gives a concrete verb + resource: 'Read up to 50 private incidents with notice delivery,' naming the scope (private incidents) and the cap. It is clear what the tool returns, but it never distinguishes itself from close siblings such as domain_status, check_domain, or acknowledge_domain_event, and the core purpose is buried behind an auth sentence.

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 real usage guidance for pagination ('Send the last event number as before for the next page'), but nothing about when to choose this tool over domain_status/check_domain/acknowledge_domain_event, and no conditions or exclusions for its use. Usage is implied by the read framing rather than stated.

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

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

Annotations already flag readOnlyHint=false, destructiveHint=false and idempotentHint=false, and the description adds real context beyond them: session plus X-Organization-Id and CSRF requirements, that data is served from cache rather than freshly collected, that monitoring is not activated, and that every tab must belong to the current account and organization. What it does not clarify is what the hinted write path actually writes, which given readOnlyHint=false is the one behavioral gap left.

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 tightly packed sentences with little filler, but the ordering is suboptimal: authentication prerequisites lead while the actual purpose of the tool arrives second. It is dense without being wasteful, though it reads more like a merged set of constraints than a front-loaded statement of intent.

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 tool with no output schema, the description covers what is returned (cached monitoring data and deadlines), the auth prerequisites, ownership scoping, batching behavior, and the exclusions. The only meaningful omission is the ambiguity created by readOnlyHint=false against a description framed around reading cached data.

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 single 'tabs' parameter is already documented as 'One to 100 owned tab IDs.' The description still adds meaning beyond the schema by imposing an ownership constraint ('Every tab must belong to the current account and organization') and by instructing how to chunk larger sets across repeated calls, which the maxItems/minItems alone do not convey.

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

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

The description gives a concrete verb and resource: 'Read cached domain monitoring and deadlines for selected saved pages.' It also draws a boundary against monitoring-activation tools by stating it 'Does not start external collection or activate monitoring,' which helps separate it from siblings like configure_domain_monitor and domain_status. It never states plainly what a 'domain portfolio' aggregates, so the differentiation is good but not complete.

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 agent learns it operates on currently-owned tabs and must be repeated in batches for large workspaces, and it is told one thing not to use it for. No sibling alternative is named for the cases it excludes, so the agent must infer which tool to reach for instead.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds genuinely useful context beyond that: private options require the account session, public observations are shared by registry domain and HTTPS origin while private settings/history stay with the account, collection gaps and source dates exist, and 'Missing data is not a healthy result.' These disclose data-scoping and freshness behavior the annotations do not.

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

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

The definition is a series of short, front-loaded sentences, but several are cryptic fragments ('Read source dates and collection gaps.', 'Pages share public observations by registry domain and HTTPS origin.') that read as implementation notes rather than agent-facing guidance. Nothing is gratuitously long, but the disjointed flow hurts 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?

With readOnly/idempotent annotations present and no output schema, the description carries most of the remaining burden and does so reasonably: it names the observation categories, flags freshness/gaps, separates public-shared from private-account data, and warns that missing data is not a pass. The main omission is any guidance on scope relative to the many sibling domain-checking tools.

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%: 'id' is documented as an owned tab ID from list_tabs, but 'guest_token' has no schema description. The text partially compensates by implying that private options require the account session (as opposed to a guest token), but it never explains what guest_token grants or how it interacts with the session. Partial compensation justifies the baseline 3.

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

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

The description enumerates what is read (registration, contact visibility, TLS, DNS, CAA, mail policies, certificate issuance, limited server comparison), which conveys the general domain-status purpose. However, it never states a crisp verb+resource scope, and nothing distinguishes it from siblings like check_domain, health, audit_url, or lab_result, which also sound like domain/service inspection tools. An agent cannot confidently route between them from this text.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternative tools for narrower checks. Statements like 'A discovered name never starts monitoring automatically' describe behavior rather than selection criteria, so the agent must infer when domain_status is the right call versus check_domain or run_tab.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful behavior: no account, no key, and no visitor e-mail capture. It does not, however, describe return shape beyond the `snippet` field.

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

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

The description repeats itself: 'one script tag' is asserted twice, and 'no account' is restated as 'no account or key'. The redundant second sentence crowds out content that would actually help, such as parameter or return detail.

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

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

With no output schema, the description does mention that the response carries a pre-assembled `snippet`, which is helpful. But it omits other response content and any deployment caveats, leaving the picture only partially complete for a generator 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%, so the schema documents all four parameters (url, brand, color, theme). The description only implies that these mirror a `/embed` query and adds no syntax or format detail. Baseline 3 applies.

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

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

The description states a specific deliverable: an already-assembled embeddable widget snippet containing the site's name and colour. It is reasonably distinguishable from siblings like get_badge, though it never names an alternative to contrast against.

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 gestures at context ('puts the audit form on your own site') but gives no explicit when-to-use, when-not-to-use, or alternatives. The agent is left to infer that this is the widget path versus get_badge or preview routes.

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

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

Annotations only say it is a non-readonly, non-idempotent, non-destructive call; the description adds the information that matters operationally: a check consumes one unit, full consumes three, and request_id must be preserved for retries. That credit-consumption and retry contract is not derivable from the annotations. It does not explain what the generated prompt contains or what happens if the allowance is exhausted.

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 purpose before the prerequisite, the cost model and the retry rule. Every sentence carries distinct operational 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?

For a 7-parameter, no-output-schema tool, the definition covers purpose, prerequisite, cost and retry semantics, which is most of what the agent needs. The remaining gap is the return shape (presumably prompt text) and what happens when the allowance is exceeded, which has no schema or annotation backing.

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

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

Schema coverage is already 86%, so the baseline is 3, but the description adds real meaning by tying the 'check' and 'full' scope values to a concrete cost of one versus three units. It reinforces the request_id retry rule and frames source=domain as the saved registration, certificate, DNS and email observations, though check_id's required-for-check behavior is only in the schema.

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

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

The description uses a specific verb and resource ('Generate a fix prompt from saved domain observations') and adds a clarifying paraphrase about preparing a coding-agent prompt from an owned report. An agent can tell it produces a prompt artifact from stored domain data, though it never explicitly names the look-alike sibling generate_fix_prompt / generate_site_fix_prompt to explain the difference.

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

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

It gives a concrete prerequisite ('Read prompt_allowance first') and states the allowance/plan constraint, which tells the agent the condition under which this call is valid. It stops short of explicit when-not-to-use guidance or naming the sibling tool to choose 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 mark this as a non-readOnly, non-idempotent mutation, and the description adds genuinely useful context beyond them: it consumes allowance units and that request_id must be held constant across retries to avoid double-charging. It does not say whether a failed generation refunds units, so a small gap remains.

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, then the prerequisite, then cost and retry guidance. Nothing is redundant with the title or 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?

For a paid, mutating generator with no output schema, the description covers the prerequisite, cost model and retry semantics, which is most of what an agent needs. It omits what the returned prompt looks like and any failure/refund behavior.

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

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

Schema coverage is already high at 83%, so the baseline is 3; the description adds real meaning by mapping the scope enum values to allowance cost (1 vs 3 units). guest_token is undocumented in both schema and description, keeping it short of 5.

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 concrete verb and resource: it prepares a coding-agent prompt from an owned report, which is clearly distinct from audit/report siblings. It does not explicitly name the adjacent tool (prompt_allowance is only cited as a prerequisite read), so sibling differentiation is implied rather than spelled out.

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?

'Read prompt_allowance first' gives an explicit prerequisite, and the per-scope unit costs (check = 1, full = 3) tell the agent which variant to pick under a budget. No explicit when-not-to-use condition, but the operating context is clear.

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

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

Annotations declare a non-read-only, non-idempotent, non-destructive mutation but say nothing about cost or retry behavior. The description adds real value beyond that: check consumes one unit, full consumes three, and request_id must be preserved across retries. It stops short of describing what the generated prompt looks like or how long generation takes.

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 that are front-loaded with the core purpose and then add prerequisite, cost, and retry facts in order of need. The second sentence ('Prepare a coding-agent prompt from an owned report...') overlaps somewhat with the first, but each remaining sentence contributes a distinct constraint.

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 9-parameter generator with no output schema, the description covers purpose, prerequisite, source selection, quota cost, and retry handling. It does not explain the relationship between 'source' and the conditional 'check_id'/'report_id' requirements, but the schema descriptions do cover those conditions.

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

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

Schema coverage is already 89%, so the schema carries most parameter meaning. The description still adds non-schema semantics: the unit cost of each 'scope' value (check=1, full=3) and the retry contract for 'request_id', which the schema only states as a format constraint.

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 ('Generate a fix prompt') and scopes it to two concrete sources: a weekly finding or a Search Console opportunity. This distinguishes it from the generic generate_fix_prompt and from generate_domain_fix_prompt even without naming them 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?

Gives an explicit prerequisite ('Read prompt_allowance first') and a hard constraint ('within the free allowance or active plan'), which tells the agent when the call will succeed. It does not, however, contrast itself against the sibling generate_fix_prompt or generate_domain_fix_prompt, so the agent must infer which generator to pick.

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 fully covered. The description adds useful context about what the call returns (findings and evidence) plus a workflow handoff, but says nothing about auth requirements for guest_token or behavior on an invalid/expired 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?

Two compact sentences with the retrieval purpose front-loaded and the alternative routing second. No filler or redundancy.

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

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

With no output schema, the description does briefly characterize the return ('findings and evidence'), and annotations cover the safety profile, so an agent can call it correctly. The only real gap is the unexplained required guest_token, which is the more minor of the two structured omissions.

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%: 'id' is documented in the schema (including the `Audit.id` provenance) while 'guest_token' is undocumented in both schema and description. The description adds no parameter meaning at all, so it fails to compensate for the uncovered 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?

The description states a specific verb ('Re-read') and resource ('audit') and clarifies scope by naming what is included ('findings and evidence'). It distinguishes itself from generation siblings like audit_site/audit_url by implying retrieval of an existing audit, though it never explicitly contrasts with them.

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

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

It explicitly routes the agent to an alternative for a defined condition: 'Use generate_fix_prompt for correction steps.' That is clear context, but there is no guidance on when to use this versus re-running an audit or what the guest_token requirement implies.

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

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

The annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds the useful detail that the payload includes markdown in addition to raw metadata, but it says nothing about access requirements for shared reports, size limits, 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?

A single front-loaded sentence with zero filler; the resource and return content appear immediately. It is a fragment rather than a full sentence, but nothing is wasted.

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

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

With no output schema, the description must sketch the return value and it does so only vaguely ('metadata and markdown'). Combined with annotations covering the safety profile and full parameter documentation, it is adequate but leaves the agent guessing about exactly what 'metadata' contains and how the badge is delivered.

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 slug parameter is documented as a '24-char public slug', so the schema carries the burden. The description's reference to 'a shared report' loosely ties the slug to a report resource but adds no format or constraint detail beyond the schema.

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

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

States a specific resource (the SVG badge of a shared report) and what it yields (metadata and markdown), which is concrete enough to distinguish it from most siblings. It never names an alternative tool and the verb is only implied by the name, so the differentiation is soft rather than explicit.

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

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

There is no guidance on when to reach for this tool versus siblings such as embed_snippet or weekly_site_report, nor any prerequisite such as the report having been shared. The only context is the phrase 'of a shared report,' which hints at a precondition but doesn't state it as a rule.

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 and non-destructive, so the safety profile is covered. The description adds real context beyond that: it uses the authenticated owner and active organization, returns immutable text, and returns 404 for a missing or foreign prompt. That error and auth behavior is exactly what annotations cannot 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?

Five short sentences, front-loaded, with the 404 behavior and auth context each earning their place. The vague opener 'Preserve the complete prompt and license' is the one line that does not clearly pay for itself.

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 lookup with no output schema and annotations covering safety, the description supplies the missing pieces: auth scope, immutability, and the 404 failure mode. Only the undocumented guest_token parameter and the exact returned payload shape leave a gap.

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

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

Schema coverage is only 50%: the id parameter is documented in the schema ('Saved prompt ID from generation or the private list') but guest_token has no description anywhere. The description adds no parameter meaning at all, so the undocumented half stays unexplained.

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 conveys that this returns an immutable saved prompt, and the name signals a read of a fix prompt, but the opening sentence 'Preserve the complete prompt and license' uses a non-retrieval verb that muddies what the tool actually does. It never states plainly that it fetches a saved prompt by ID, nor does it distinguish itself from get/generate siblings such as generate_fix_prompt or list_domain_fix_prompts.

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?

'Use it only for license.domain' and 'does not authorize deployments or infrastructure changes' give scope limits, but there is no guidance on when to call this versus generate_fix_prompt (create) or list_domain_fix_prompts (enumerate). The agent is given restrictions without a routing rule.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structurally. The description's only added behavioral fact is the account-scoping constraint ('owned by the signed-in account'), which is genuinely useful but thin; nothing is said about behavior when the id is not owned or does not exist.

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

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

A single front-loaded sentence with zero filler; the scope constraint is stated immediately and nothing redundant is included.

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, idempotent read with rich annotations and a fully documented single parameter, the description covers purpose and ownership scope adequately. The main omission is what a not-found or not-owned id yields, though no output schema exists to carry that either.

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

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

Only one parameter, and schema description coverage is 100% — the schema already explains that 'id' comes from list_sites or add_site. The description adds no format or syntax detail beyond that, so the baseline of 3 applies.

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

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

States a specific verb ('Read') and resource ('one site') with scope ('owned by the signed-in account'), which is enough to distinguish it from the plural list_sites. It does not, however, name a sibling or otherwise explicitly contrast itself with list_sites or audit_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?

Usage is implied by 'one site' plus the required id — the agent can infer this is the single-record lookup — but there is no statement of when to prefer it over list_sites or audit_site, and no prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and a closed-world scope, so safety is covered structurally. The description adds only the 'Copy and checks' framing about what is being returned, which hints at output content but does not say what happens for an unknown slug or how large the payload is.

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

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

A single, front-loaded sentence with no filler. It is efficient, though the phrasing 'Copy and checks of one micro-tool' is slightly ambiguous and could be tighter.

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

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

For a simple two-parameter read tool with no output schema, the description is minimally adequate: it identifies the resource and identifier. It leaves gaps on failure behavior for invalid slugs and on what the returned copy/checks actually contain, which would help an agent interpret results.

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 both parameters carry their own descriptions, including the language fallback behavior, so the schema does the heavy lifting. The description's example slug ('title-tag-checker') is a useful format hint that the terse schema label 'tool slug' does not provide, keeping it at the baseline 3.

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

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

The description names a specific resource ('one micro-tool by slug') and gives a concrete example identifier ('title-tag-checker'), so an agent understands it fetches a single tool definition. It stops short of distinguishing itself from the sibling list_tools, which enumerates tools, so it stays 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?

There is no statement of when to use this tool versus alternatives such as list_tools, nor any precondition (e.g. that the slug must already exist). The example slug implies a lookup pattern but provides no 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveness false. The description adds the deploy-commit context, which annotations cannot express. It does not explain the return shape (though no output schema exists, so this is relevant) or latency/polling behavior, but the annotation coverage lowers the bar.

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

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

A single sentence, front-loaded with the two return values and then the deploy context. No 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?

For a zero-param health-check tool this is adequate, but without an output schema the description could say more about what 'liveness and commit' looks like or how often to poll. It covers the 'what' but not the 'how to interpret'.

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?

Zero parameters, so baseline is 4. No parameter meaning to convey, and the description correctly says nothing about inputs.

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 what it returns: liveness and the commit deployed right now. This is a specific resource pair and distinguishable from siblings like audit_url or check_domain, though it doesn't explicitly name 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?

The phrase 'it is how the smoke waits for its own deploy' implies when to use it – during a deploy smoke test – but gives no explicit when-not-to-use or alternative. An agent can infer context but must guess whether it's also useful for general health checks.

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 the safe-read profile (readOnly, idempotent, non-destructive, closed-world), and the description still adds material context: browser-session auth, owner-only authorization, realtime-updating data, and explicit privacy exclusions (no user identity, typed text, or screen recording). The privacy note tells the agent what it will NOT receive, which is genuinely useful for framing answers.

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?

Short declarative sentences, front-loaded with what is read and the time window, then constraints, then data-freshness and privacy. Every sentence carries distinct information with no restatement of the name or annotations.

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

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

For a single-parameter, read-only tool with no output schema, the description covers what data is returned, the freshness model, the auth/permission gate, and privacy boundaries. An agent has everything needed to decide to call it and to describe the result responsibly.

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

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

Schema description coverage is 100% and the single parameter (id = "Owned Site.id.") is fully documented in the schema, including the ownership tie-in the description already asserts. The description adds no format, range, or syntax detail beyond this, so baseline 3 applies.

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

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

The description names a specific verb ("Read") and a concrete composite resource set: installation, actions, paths and the ordered conversion funnel, scoped to the last seven days for the owned site. No sibling (audit_site, get_site, search_console) covers journey/funnel data, so the agent can distinguish it 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?

It states clear preconditions and audience: "Requires the account's browser session" and "Only this site's owner can read it." The seven-day window also implicitly bounds when the tool is the right source. It stops short of naming an alternative tool or an explicit when-not-to-use condition, so it is strong context rather than full routing.

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 value beyond them: long-poll semantics, a 0–25 second ceiling on `wait`, the fact that an expired wait returns `status: running`, and the instruction to repeat. It does not detail response structure or rate limits.

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

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

Three sentences, but the long-poll behavior is stated twice in near-identical wording ('answers as soon as a running test finishes' repeated). The repetition wastes space, though the rest is front-loaded and free of 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?

With no output schema, the description does carry the burden of describing returns and it names the statuses and payload (scores, metrics, biggest savings, failed, running). It is nearly complete for a polling read tool; only the exact response shape and error/failure conditions are left implicit.

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

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

Schema coverage is 67% and the schema's `wait` entry only says 'seconds to wait, 0–25'. The description clarifies what that wait actually does (returns as soon as a running test finishes, or after `wait` seconds with `status: running`), adding meaning not present in the schema.

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

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

States the resource (lab test results of an audit, mobile and desktop) and the possible states (running, finished with scores/metrics/savings, failed). It never uses an explicit retrieval verb and doesn't distinguish itself from the similarly named sibling `lab_test`, but the resource and outcome set are clear.

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 concrete polling mechanics (use `wait`, repeat until it is not running), which is useful operational guidance, but never says when to choose this over `lab_test` or `get_audit`, and gives no prerequisites beyond the implied guest_token.

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?

Far exceeds the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false) by disclosing the 202 async contract, 25s–2min duration, that the score is unchanged, where the summary lands (summary.lab.<strategy>), dedup behavior per strategy, and concrete throttling limits (4 concurrent, 6/hour, 500/day). This is exactly the behavioral context an agent needs to use an async mutation safely.

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 well with the core action first, but it is heavily redundant: 'Answers 202 at once', the timing range, and 'does not change the audit score' each appear twice verbatim, bloating a description that could be half 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, the description carries the full load and does: it explains the 202 return, how to retrieve results, where they persist, timing, and rate limits. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is a moderate 67%; the description adds meaning beyond the schema by tying 'strategy' to the storage path summary.lab.<strategy> and to the dedup rule (same strategy won't double-run). It does not clarify guest_token, which the schema also leaves undocumented.

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 ('Starts a lab test of an audit's page') and immediately qualifies it as a Lighthouse run via Google PageSpeed Insights with the four measured categories. It is unambiguously distinguishable from its read counterpart lab_result and from audit_site/audit_url.

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 routes the agent to lab_result to read results, and gives a when-not condition ('calling again while the same strategy is running does not start a second test'). It does not, however, contrast itself against the other audit-running siblings (audit_site, audit_url, run_tab), so the 'why this tool vs those' choice 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description correctly spends its words elsewhere: cost ('free'), pagination ceiling (100 rows plus up to three earlier receipts), cursor mechanics, and owner/organization scoping. That is meaningful behavior an agent cannot read off the annotations, though return shape beyond 'rows' is not described.

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?

Short, front-loaded with the action and its timing, then dense operational facts in single clauses. 'Follow _links.next' is a compact and useful pointer to the output field. Slightly choppy, but 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?

With no output schema, the description carries the return burden and does so adequately: page size, extra receipt rows, and the _links.next cursor. Auth scope (owner plus active organization) is stated. Only the guest_token path and the actual row fields remain unexplained.

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 75%, and the description adds genuine semantics beyond the schema by stating that language and source filters must be carried forward when following the cursor, which is exactly the pitfall an agent would hit with id/language/after. The undocumented guest_token is left unaddressed.

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 list operation on a specific resource ('saved audits prompts'), which the name and the 'audits' qualifier scope apart from the domain/site fix-prompt siblings. It stops short of naming those siblings (list_domain_fix_prompts, list_site_fix_prompts) so the differentiation rests on the tool name rather than the prose.

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?

'before generation' and 'Listing is free' imply the intended moment to call this (check for existing saved prompts instead of paying for generation), which is a real usage cue. There is no explicit when-not, no prerequisites, and no named alternative such as generate_fix_prompt or get_fix_prompt.

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 the safe read-only/idempotent profile, and the description adds genuinely new context: listing is free, at most 100 rows per page plus up to three audit receipts, follow _links.next, and results scoped to the authenticated owner and active organization. These pagination and scope traits go beyond the structured annotations, though rate/error behavior is untouched.

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 and composed of short declarative sentences, each carrying information. 'Find saved tabs prompts before generation' is somewhat cryptic, but there is little wasted text.

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

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

With no output schema, the description covers pagination (cursor, _links.next, page cap), cost, and ownership scope, which is most of what an agent needs to call a list tool correctly. It stops short of clarifying the domain-vs-site/audit distinction, which is the main remaining gap.

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

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

Schema coverage is 80%, so the schema already documents the id, after, source, and language parameters. The description reinforces the language and source filters and the cursor mechanism but adds no syntax or values beyond the enumerated schema, and guest_token is never addressed. 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 verb is loose ('Find') and the resource is described as 'saved tabs prompts before generation', which does not clearly say these are domain fix prompts. It never distinguishes itself from close siblings like list_site_fix_prompts, list_audit_fix_prompts, or generate_domain_fix_prompt. The purpose is inferable but not stated with specificity.

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?

Phrases like 'before generation' and 'Keep language and source filters when following the cursor' imply the listing workflow and pagination discipline, but no alternative tool is named and no explicit when/when-not condition is given. Usage is implied rather than prescribed.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description still adds meaningful context the annotations do not carry: listing is free (no quota cost), page size is capped at 100 rows with up to three earlier audit receipts appended, and results are scoped to the authenticated owner and active organization.

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 purpose, then pagination and scope facts, with no filler sentences. Slightly compressed phrasing ("sites prompts") costs clarity without saving much 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, the description carries return-value burden and does so reasonably: page size, the extra audit receipts, the _links.next pointer, and ownership scoping. An agent can call and paginate it correctly; only the sibling differentiation 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 83%, so the structured fields already document most parameters. The description adds a rule the schema does not state: language and source filters must be preserved when following the cursor, which is essential for correct pagination. It does not, however, mention report_id's dependency on source=weekly beyond what the schema says.

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?

"Find saved sites prompts before generation" identifies the verb (find/list) and the resource (saved site fix prompts), and the title reinforces it. However, "sites prompts" is awkward shorthand, and the description never distinguishes this tool from the closely named siblings list_audit_fix_prompts and list_domain_fix_prompts, leaving the agent to infer the scope from 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?

The phrase "before generation" implies a usage moment, and "Keep language and source filters when following the cursor" gives a concrete procedural rule for pagination. But there are no explicit when-not conditions and no named alternatives among the three sibling list_* prompt tools, so the routing decision 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 declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds the 50-item page cap and the cursor-following protocol, which are genuine behavioral details beyond annotations, but says nothing about ordering, result shape, or what happens when the account owns no sites.

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 terse sentences, front-loaded with the core action and scope, with zero filler. The second sentence is telegraphic ('Follow next_cursor') and slightly fragmentary, but nothing is wasted.

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

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

For a two-parameter, zero-required list tool with no output schema, the description covers the page bound and paging mechanic but never characterizes the returned records or ordering, leaving an agent to infer the response shape from the schema's host description.

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

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

Schema description coverage is 100%, so both parameters are already well documented (host semantics, including 'Does not create a site', and cursor provenance). The description's only added hint is 'Follow next_cursor', which largely restates the cursor schema description; 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 ('Read ... sites') plus a scope qualifier ('owned by the signed-in account') and an explicit page-size bound. It does not name the sibling get_site or otherwise disambiguate list-vs-single, 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 instruction 'Follow next_cursor' gives practical guidance on how to page through results, which implies continued use until exhausted. However, there is no explicit when-to-use-this vs get_site, and no stated exclusions or 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?

Annotations already cover readOnly, idempotent, non-destructive, and closed-world. The description adds useful behavioral context: it discloses that one call loads both saved pages and the active page's last report, and mentions the X-Organization-Id header for signed-in accounts vs a guest's temporary workspace. However, auth requirements are stated loosely and it doesn't clarify how guest_token interacts with the signed-in path.

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

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

The core purpose is front-loaded, but the description pads with UI narrative ('The UI groups pages by site in Projects and opens each site in a work tab. The introduction stays in Welcome.') that is tangential to calling the tool. Several sentences restate the same grouping/loading idea without adding callable detail.

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

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

For a simple read-only list tool with full annotation coverage and no output schema, the description covers return content (saved pages plus the active page's last report), grouping behavior, and auth context. The main gap is the undocumented guest_token, but overall it is sufficient for correct invocation.

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

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

Schema description coverage is 0% for the single required guest_token parameter, so the schema gives no meaning. The description compensates only indirectly by referring to guest/session and a guest's temporary workspace, but never defines the token's format or where it comes from. This is a bare-minimum compensation for a 1-param tool.

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

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

States a clear verb (lists) and resource (owner's saved pages/tabs), and adds that the active page's last report is included. An agent can distinguish it from create_tab/run_tab, though the 'tabs' vs 'pages' vs 'group by site' framing is somewhat muddled and siblings like tab_history are never explicitly contrasted.

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

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

No when-to-use or when-not-to-use guidance is given, and no alternative tool is named. The only contextual cue is the guest vs signed-in distinction, which hints at audience but doesn't tell the agent when to pick this over tab_history or list_sites.

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 no operational context of its own — no mention of result count, ordering, pagination, or what a returned entry contains — leaving the burden unmet for a listing 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?

It is a single, short, front-loaded sentence with no filler, which is good. However, it terminates in an ellipsis instead of enumerating the set, leaving the sentence deliberately incomplete rather than concise.

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

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

There is no output schema, so the description must convey the return shape, and it only gestures at it with a trailing list plus ellipsis. Combined with the undefined term 'micro-tools' and no sibling differentiation, an agent lacks enough to invoke this correctly.

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

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

Schema description coverage is 100% and the single 'language' parameter is fully documented in the schema including the pt/pt-BR fallback behavior. The description adds nothing about the parameter, so the baseline 3 applies.

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

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

States the verb 'lists' and a resource, 'micro-tools', but never defines what a micro-tool is; the parenthetical (title, meta, canonical, OG, JSON-LD) could be describing the tools themselves or the fields they check. It also fails to distinguish this from the sibling get_tool, so an agent can't confidently separate them.

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

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

There is no statement of when to call this rather than get_tool, list_sites, or list_tabs, and no prerequisites or exclusions are given. Usage must be inferred entirely from the tool name.

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

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

Goes well beyond the annotations by disclosing auth requirements (session, X-Organization-Id, CSRF), the 25-item selection cap, registrable-domain de-duplication, server-side re-validation of account/organization/revisions, and staleness semantics ('a stale preview changes nothing'). This is meaningful procedural context the annotations do not carry, though the exact nature of what the preview reveals is left 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?

Short, information-dense sentences with no obvious padding. Minor structural quibble: the auth prerequisite is front-loaded ahead of the actual purpose, which slightly delays the reader understanding what the tool does.

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

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

Covers auth, selection limits, de-duplication, server re-validation and staleness for a two-parameter preview tool. With no output schema, one gap remains: the description never says what the preview actually returns or displays, which an agent invoking a 'preview' would benefit from knowing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the registrable-domain de-duplication rule ('repeated registrable domains count once') is not captured by uniqueItems/maxItems, and 'before changing renewal notices' contextualizes lead_days.

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 ('Review/preview') and resource (selected domains' renewal notices), so the tool's job is clear: preview before committing alert changes. It never names the sibling that actually applies the change (apply_domain_alerts), leaving differentiation to inference.

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?

'before changing renewal notices' implies the when-to-use context (prior to applying), which is genuine guidance. However, it does not explicitly name the alternative tool or state exclusions, so the agent must infer the preview-then-apply workflow.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds only the pre-generation timing cue and nothing about what the response contains or what 'remaining' means numerically; with no output schema, that gap falls on the description.

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

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

One short sentence, front-loaded with the verb and resource, no filler. It is efficient rather than padded, though its brevity contributes to the gaps in other dimensions.

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, an undocumented optional parameter, and no annotations covering return behavior, the description is too thin. It doesn't say what a 'prompt unit' is or how the remaining count is returned, leaving the agent unable to interpret the result.

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 single optional guest_token parameter is never mentioned in the description. The schema names it but gives no type semantics, format, or reason for passing it, and the description does nothing to compensate.

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 verb (read) and resource (remaining prompt units), but 'prompt units' is ambiguous jargon and the description doesn't clarify whether this is a quota, credit balance, or generation budget. No sibling does anything similar, so differentiation isn't the issue, but the resource itself is underspecified.

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?

'before generating' gives an implied timing condition for calling the tool, which is more than nothing. However, it doesn't state what to do with the result, whether calling is required, or what happens if the allowance is zero.

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?

Rich operational context is supplied (three starts/account/day, one per site, 170s deadline, 26h report expiry, partial results). However, it directly conflicts with the idempotentHint=false annotation by asserting 'A repeated request reuses today's review' and 'Retries return the same review' — i.e., identical calls produce no new effect. The description also repeats these points multiple times rather than adding coverage.

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

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

The text is highly redundant: the three-starts-per-day rule is stated twice, the single-review-per-day rule twice, and 'Do not claim complete safety from a partial result' is restated as 'Partial results do not establish safety.' Useful facts are buried in repetition rather than 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 mutating, quota-limited, open-world tool with no output schema, the description does cover safety, retries, quota and expiry, which is substantial. But the redundant phrasing and the unresolved idempotency conflict leave an agent unsure how repeated calls actually behave.

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

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

There is a single parameter with 100% schema description coverage ('Owned tab ID from list_tabs'), so the schema already carries the semantics. The description adds no meaning for the id argument; baseline 3 applies.

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

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

The description states a concrete verb+resource: 'Start a TLS review of the saved HTTPS origin.' This distinguishes it from read-style siblings like connection_review and cancel_connection_review, though it never names them 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?

It gives conditions (requires account session, X-Organization-Id, CSRF for writes) and one exclusion ('GET never starts a scan'), but the exclusion is phrased about HTTP methods rather than naming the alternative tool, and there is no explicit 'use X instead when...' routing.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true and idempotentHint=false, so the agent knows this is a non-idempotent, world-touching action. The description adds only the target ('the tab's URL') and says nothing about whether the audit is async, how results are retrieved (get_audit / tab_history), or whether it consumes quota.

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

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

A single front-loaded sentence with zero waste, which is structurally fine. However, at six words it is arguably under-specified rather than concise, so it lands at the minimum viable level.

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 non-idempotent action tool with two required parameters (one undocumented) and no output schema, the description should say more about what happens after the run and how to obtain results. It leaves the agent without enough context to invoke or follow up 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 only 50%: 'id' is documented but 'guest_token' has no description anywhere. The description mentions no parameters at all, so it does not compensate for the gap, particularly for the undocumented auth token.

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

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

The description states a specific verb ('re-audits') and a specific resource ('the tab's URL'), which is far more useful than the bare title 'Run tab'. It does not distinguish itself from siblings such as audit_url or audit_site, which likely perform similar audit actions on different targets, 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?

There is no guidance on when to use this tool versus audit_url, audit_site, or watch_tab, nor any mention of prerequisites such as whether the tab must already exist. The agent must infer usage entirely from the name.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond them: the shared 240 writes per site per UTC day, the watch-package-dependent limit, and that saves use the expected version (optimistic concurrency). It could have stated what existing saved queries are replaced, but the added quota/versioning detail is 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?

The core save constraint is front-loaded, but the three-search limit is stated twice ("three without a watch package" and "Without a current watch package, an account tracks up to three searches"), which is redundant. Otherwise the size is appropriate for the tool.

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

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

For a mutation tool with destructive annotations, no output schema needed, and fully-covered parameters, the description supplies the missing operational envelope: quota limits, watch-package dependency, and version-based concurrency. Nothing essential to calling it correctly is absent.

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 id, queries, and version are already fully documented (queries length/count, version '0 initially; then the current settings version'). The description corroborates the queries limit and the versioning behavior but adds no new syntax or format beyond the schema, so baseline 3 applies.

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

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

The description states a clear verb+resource ("Save up to ten searches") and the reason ("for the weekly report to track"), so an agent understands the mutation immediately. It does not explicitly contrast itself with siblings like weekly_site_report or ai_search_history, so it falls short of full sibling differentiation.

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

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

Quota context (10 vs 3 searches depending on watch package) implies when the tool is useful, but there is no explicit when-to-use vs alternatives routing. No sibling is named and no prerequisites or exclusions are given, 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 write/destructive/idempotent behavior, but the description adds substantial value: the watch-package prerequisite, the 409 response with `limit` and `plans`, report scheduling (first immediate, then weekly), and optimistic-concurrency ('Saves use the expected version'). It stops short of explaining what toggling off does to existing competitors.

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

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

Front-loaded and reasonably sized, but the watch-package prerequisite is stated twice ('Turning on needs a watch package in force. Turning on needs a watch package in force and a free site in it...'), which is redundant and wastes a sentence.

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

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

For a mutating, concurrency-sensitive tool with no output schema, the description covers prerequisites, an error case, report timing, and version semantics adequately. Minor gaps remain on the effect of turning reports off, but the core call requirements are present.

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 schema already documents all four parameters, establishing the baseline of 3. The description's 'set up to 3 competitors' and 'Saves use the expected version' lightly reinforce but do not deepen the schema's own descriptions.

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 ('Turn the weekly report of a site on or off and set up to 3 competitors') with clear scope. It does not, however, distinguish itself from sibling tools like weekly_site_report or weekly_site_report_history, leaving the agent to infer this is the save/mutation variant.

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

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

It gives a prerequisite ('needs a watch package in force') which is useful context, but offers no explicit when-to-use guidance or references to alternatives among the weekly_site_report* siblings. 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?

The description goes well beyond the annotations (which only cover read-only/idempotent safety) by disclosing sampling limits (28 days, at most 50 queries and 50 pages), the fact that coverage is partial and tied to this property rather than market volume, that positions are impression-weighted averages rather than fixed SERP ranks, and that credentials and raw provider responses are never returned. It also flags collection failure as something to verify before acting. This is exactly the kind of behavioral 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?

The opening sentence is well front-loaded with the core capability, but the text is long and repeats itself: the 'not market search volumes' caveat appears twice, and the positions 4-20 / up-to-20-queries limits are restated in separate sentences. Repetition of the same caveats crowds out room for other 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 no output schema, the description must explain what comes back, and it does: keywords, opportunities, the terms array, daily history and comparison windows, plus the statistical caveats on how positions and impressions are computed. That is close to sufficient for a read-only, single-parameter tool; only the workflow ordering relative to connect/sync siblings remains unstated.

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 single 'id' parameter is already documented in the schema as coming from list_sites or add_site, so the baseline is 3. The description instead spends effort describing a 'terms array' with daily history and 7-day comparisons that does not exist in the input schema, which adds confusion rather than parameter meaning.

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

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

The description states a specific verb and resource: read own-site keyword data (keywords, opportunities, tracked queries, daily history) for a given site ID. It also draws a clear boundary against market search volumes, which helps separate it from visibility-oriented siblings. However, it never names or contrasts with competing siblings such as sync_search_console, track_search_queries or ai_search_visibility, so differentiation is only 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?

It gives task-level guidance: 'Check dates, partial coverage and collection failure before proposing edits' and 'Use queries for keyword research and opportunities for average positions 4-20.' That is useful workflow direction, but it is guidance on reading the output rather than on when to call this tool instead of a sibling. No explicit alternatives or prerequisites (e.g., connect_search_console first) are named, so usage is implied rather than stated.

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

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

The auth requirements (session, X-Organization-Id, CSRF) and the 409-on-conflicting-revision detail are genuinely useful additions beyond the annotations. However, 'An identical retry is idempotent' directly conflicts with idempotentHint=false, whose MCP meaning is precisely that repeated identical calls have no additional effect.

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, short sentences with no filler; each clause carries information. It is slightly mis-front-loaded, leading with auth prerequisites rather than the action, and the DNS/settings sentences reference parameters the schema does not expose.

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 mutation tool with no output schema, it covers the safety-relevant ground: auth, preservation of omitted settings, idempotency behavior, and the conflict error. The completeness is undermined by describing a DNS/selectors surface that the schema does not have, leaving the agent unable to reconcile the two.

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

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

Schema description coverage is 100%, so the baseline would be 3. But the description references 'dns', 'selectors', and 'rotating_addresses' — none of which exist in the input schema, which only has id, revision, and manual_expires_on. This stale text actively misleads an agent building a call.

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

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

The opening line states a specific verb and resource: 'Set or remove the private manual expiry.' That is clear enough to separate it from siblings like domain_status or configure_domain_monitor. It stops short of explicitly naming an alternative tool, so it does not reach 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?

It gives conditional guidance ('Send manual_expires_on, dns, or both. Omitted settings are preserved.'), which tells the agent how to shape a call, but never says when to reach for this tool versus a sibling such as configure_domain_monitor or domain_history. Usage is implied rather than scoped.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, but the description adds genuinely new behavioral facts: a durable daily reservation that repeated calls cannot bypass, an hourly schedule sharing that reservation, and 24-hour retry with preservation of the last good sample on failure. These rate-limit and failure-recovery semantics are exactly the kind of context annotations cannot 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?

The action is front-loaded in the first sentence, but the last two sentences are near-duplicates of the reservation point: 'Repeated calls cannot bypass the daily reservation' and 'This route cannot force an extra collection' say the same thing twice. Trimming that redundancy would sharpen the definition.

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

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

With no output schema, the description should explain more about what a run produces or returns, and what 'sample' means in this domain. It does cover scheduling and failure behavior well, but leaves the agent without a clear picture of the operation's outcome or its connection prerequisite.

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% — the single 'id' parameter is documented as 'Site ID from list_sites or add_site.' The description contributes no additional meaning about the parameter, so the baseline of 3 applies.

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

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

The description says it will 'collect a due sample', which names an action but uses opaque jargon rather than stating that it syncs Search Console data. The resource is unclear and it does not differentiate itself from siblings such as search_console or connect_search_console. An agent can infer intent from the tool name but not confirm it from the text.

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 a when-not condition ('cannot force an extra collection', 'cannot bypass the daily reservation'), which tells the agent not to expect this route to trigger an unscheduled collection. However, it never states when to prefer this over search_console or connect_search_console, or what preconditions exist.

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, non-open-world behavior, and the description adds genuinely new context: unlimited retention, comparison keyed by finding code and never by message, and URL-based matching for pre-watch runs. It stops short of covering ordering guarantees or pagination beyond the schema's limit.

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 the core purpose before the payload shape and the legacy-URL edge case. Dense but each sentence carries information; the retention remark is slightly expendable.

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 usefully sketches the return shape (score, counts, change with delta and broke/fixed lists). Combined with annotations covering safety, an agent has enough to call it correctly; only parameter-level guidance and pagination behavior are thin.

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

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

Schema coverage is 67% (guest_token has no description), and the description adds nothing about `id`, `limit`, or the auth token — the newest-first/default-20/max-100 semantics live entirely in the schema. With partial coverage and no compensating text, this sits at the minimum-viable baseline.

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

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

States a specific verb and resource: reading a tab's previous runs and the deltas between consecutive runs. The described payload (score delta, appeared/disappeared findings) makes it unambiguous versus siblings like domain_history, weekly_site_report_history or list_tabs, which operate on other resources.

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?

"Every run has always been kept; this is where you read the series" implies when to reach for this tool, but no alternatives (domain_history, get_audit, list_tabs) or exclusions are named, and no prerequisites for the watch feature are spelled out. Usage is implied rather than stated.

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

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

Annotations declare destructiveHint=true and idempotentHint=true; the description earns its keep by explaining what actually happens on replace: removed queries go inactive but keep stored history, and saving schedules Search Console collection. The e-mail/site-package dependency adds real operational context. Points lost only for the vague term 'inactive'.

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

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

The first sentence is well front-loaded, but the description then duplicates itself: 'Removed queries keep their stored history' and 'Removed queries become inactive; their stored history is retained' say the same thing, as do the two e-mail alerts / site package sentences. Roughly half the text is redundant.

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

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

For a replace-all mutation with no output schema, the agent learns the destructive nature, the read-first prerequisite, history retention, and the scheduled collection side effect. Only minor gaps remain, such as what a failed partial save does.

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 both params are already documented, including the 1–300 character / 20-item limits. The description restates the 20-item cap and 'exact queries' but adds nothing about the 'id' parameter or query syntax beyond the schema.

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

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

Opens with a specific verb and resource: 'Replace the site's tracked query selection (up to 20).' That distinguishes it from save_ai_search_queries and search_console well enough, though it doesn't name a sibling explicitly.

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

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

'Read search_console first to preserve existing selections' gives a concrete prerequisite workflow step, which is valuable for a replace-style operation. It stops short of naming the sibling tools it supersedes or stating 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 already flag destructiveHint=true and idempotency=false, and the description adds real behavioral detail beyond them: auth requirements, the specific 403 error code, alert-on-drop-but-never-on-improvement semantics, and a per-account watch limit. It omits what happens to existing state when monitor is set to false and any rate-limit specifics.

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

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

The core behavior is stated twice almost verbatim ('re-audits the page once a day and e-mails when the score drops or a new error/warning appears' then again under monitor:true), which is redundant padding. The auth and limit sentences do earn their place, but the duplication costs a point.

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

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

For a 4-parameter mutation tool with no output schema, the description covers auth, error behavior, alert semantics, and quota limits, which is nearly enough to call it correctly. It leaves unaddressed what disabling watch does to stored watch state and whether the monitor_email change applies retroactively.

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

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

Schema description coverage is 100%, so the baseline is 3. The description corroborates monitor=true semantics but adds no format, default, or edge-case detail beyond what the schema already documents for id, monitor, guest_token, and monitor_email.

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 precise verb+resource: 'turns the daily watch on or off for a tab', and immediately explains what watching entails (daily re-audit + e-mail alert). This is clearly distinguishable from siblings like run_tab or list_tabs, which do not toggle the recurring monitor.

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

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

It gives clear operating context: an account/session cookie is required, a guest token yields 403 account_required, and accounts have a limited number of watched pages. It does not name sibling alternatives or state when to prefer them, 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 declare readOnly, idempotent, destructive=false, and openWorld=false, so the safety profile is covered. The description adds meaningful behavior beyond that: the report is generated weekly, checks the first 500 sitemap URLs, and reading does not trigger generation. This cadence/scope detail is genuinely additive, though the key point is stated twice rather than expanded.

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

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

The content is reasonable in length, but 'Reading never runs the report' is duplicated verbatim at the start and the end, wasting a full sentence. The middle sentence packs scope and cadence well, but the redundancy undercuts tightness.

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

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

There is no output schema, so the description must convey return content, and it does: it lists what the report contains (new and fixed problems, new pages, competitor pages). Combined with annotations covering safety and 100% schema coverage on inputs, an agent has enough to call it correctly, though the report's exact format remains unspecified.

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% ('id' = site owned by the account, 'lang' optional for Portuguese), so the schema fully documents both parameters. The description adds no syntax, format, or meaning beyond what the schema provides, which is the baseline when the schema does the work.

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

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

States a specific verb and resource ('Read the weekly report of a site') and enumerates its contents (changes since last week, competitor new pages, findings). Clear enough to distinguish the read action from generating a report, but it never names or contrasts with siblings like weekly_site_report_history or save_weekly_site_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?

The repeated 'Reading never runs the report' implies this tool reads an existing report rather than generating one, which is useful context. However, no explicit when-to-use/when-not guidance or alternatives are given, so the routing to weekly_site_report_history or save_weekly_site_report 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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds only that the result is a single report, with no mention of pagination, report freshness, or what happens when the id is unknown. Acceptable but not additive.

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

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

A single front-loaded sentence with no filler; the lookup mechanism is stated first. It is arguably too terse to carry usage guidance, but nothing in it 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?

For a simple read-only tool with complete annotations, a 100%-covered schema and no output schema, the description is minimally sufficient. It omits the sibling differentiation (history vs current weekly report) that would help an agent pick correctly.

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

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

Schema description coverage is 100%, so 'id', 'lang' and 'report' are already documented in the schema. The description only echoes the id-based lookup and adds no syntax, format, or constraint detail beyond 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 ('Read one weekly report of a site's history') and the lookup key ('by its id'), which is enough to distinguish it from sibling 'weekly_site_report' (the current report) and 'save_weekly_site_report'. It does not explicitly name or contrast those siblings, so it falls short of 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?

No when-to-use guidance, no preconditions, and no reference to the obvious alternatives in the sibling list such as 'weekly_site_report' or 'save_weekly_site_report'. The agent must infer that this retrieves an archived report rather than the current one.

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