CookiePal

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

Annotations only say this is a non-destructive, non-idempotent write; the description goes much further by disclosing the per-organisation daily quota, that nothing is scanned server-side, that a banner build is queued, and that other tools will keep using the default domain afterwards. These are exactly the operational facts an agent needs before invoking a mutating tool.

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

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

Four sentences, front-loaded with the action and side effect, then quota and workflow caveats — no filler. Slightly dense, but each sentence carries distinct information.

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

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

For a single-parameter mutation with annotations and an output schema, the description covers the important unknowns: quota limits, server-side non-action, queued banner build, and default-domain behaviour of siblings. Nothing an agent needs in order 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 description coverage is 100% and the schema already documents URL normalization, leading-www stripping and port refusal. The description adds no additional meaning about the 'domain' argument beyond calling it a 'website domain', 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 opens with a specific verb and resource — 'Adds a website domain to the connected CookiePal account' — plus the immediate side effect of queueing a banner build. This clearly separates it from read-only siblings such as list_domains and whoami, so an agent can pick it without inspecting 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 gives real usage context: the tool is for the free plan, applies the same checks as the dashboard, and is capped at 10 domains per organisation per day. It also explains the downstream workflow ('the result says how to run the first scan on the user's computer') and the cross-tool default-domain caveat, though it never names start_scan or list_domains as explicit next/alternative calls.

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 readOnlyHint=false, the description usefully explains why: it writes a local reading back onto the domain, and states that re-running is safe ("run this again any time"), matching idempotentHint=true. It also pre-empts a likely misinterpretation by saying the result is never a compliance verdict. It does not say what happens to a prior reading when a new one is recorded, which is the one material behavior left implicit.

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

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

Purpose and side effect are front-loaded, and every following sentence carries real constraint value. The environment paragraph is somewhat repetitive ("does not stand in for it" restates the cloud-vs-local point), costing a little tightness but not clarity.

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

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

The description covers the two things an agent could get wrong on this tool: where it can legally run, and what the result must not be interpreted as. Return values are handled by the output schema, and the nested reading object is explained in the schema, so nothing essential is missing.

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

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

Schema description coverage is 100%, so url, seenAt, reading, and domainId are already documented, including the instruction that reading is exactly what the gcm check command returned. The description adds no parameter-level detail beyond that baseline, which is acceptable but not additive.

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 a specific verb-and-resource pair ("Reads Google Consent Mode on one of your CookiePal domains") and adds two concrete behaviors: it names the problem if one exists, and it records the result on the domain. That is unmistakably distinct from siblings such as plan_check, verify_installation, or start_scan without needing to compare 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 gives clear usage context ("Run this again any time to re-check") and, more importantly, hard environmental exclusions: it must run from the CookiePal plugin in Claude Code on the user's own machine (terminal/desktop/IDE), and claude.ai, Claude Code on the web, or any external crawler cannot substitute. What it lacks is a direct pointer to which sibling to use when the local plugin is unavailable, leaving that inference to the agent.

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=true, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description usefully adds that results are reported per cookie and that the operation is scoped to a single domain, but it does not disclose whether unknown cookies are created, how partial failures are surfaced, or what permissions are 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 tight sentences, with the core action and scope front-loaded and the value source following. The enumerated category list partially duplicates the schema enum and could be shortened to the package reference, but overall 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?

An output schema exists, so return shape needs no explanation, and the annotations cover idempotency and non-destructiveness for a write operation. What remains thin is the create-versus-update semantics for cookies not already known to the account, which matters for a mutating batch tool.

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

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

Schema coverage is 50% and domainId already carries its own description, so the schema does the heavy lifting. The description's main addition is naming @cookiepal-oss/cookie-db as the authoritative source for category values, but the enumerated list it repeats is already present in the schema enum, and the batch size limit and per-item required fields are left to 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 gives a specific verb and resource ('Sets the category for a list of cookies') plus scope ('on one of your CookiePal domains') and a batch-report side effect. No sibling tool in the list performs classification, so the agent can place it unambiguously, though the description never explicitly says what it is not.

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

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

Usage is only implied: it is for assigning categories to a batch of cookies, and the category must come from the @cookiepal-oss/cookie-db package. There is no statement of when to prefer this over any other tool, no prerequisites (domain access, existing scan data), and no guidance on whether cookies must already be known to CookiePal.

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 mutation, idempotence, and non-destructive annotations, it discloses the interactive browser side effect, conditional sign-in or sign-up, and the resulting account and default-domain context. It does not explain what happens when a client is already connected or when browser authentication is cancelled or fails.

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

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

Two sentences front-load the connection and authentication behavior, then cover the returned context and install-linking consent. They are fairly dense, and the second substantially duplicates schema guidance, but there is no filler.

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

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

For a two-parameter tool with full schema coverage, an output schema, and safety annotations, the description supplies the important missing operational context: browser interaction, conditional account creation, and how the reported domain affects other tools. An agent has enough information to invoke the connection flow and handle optional install linking correctly.

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

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

Schema coverage is 100%, and the schema already documents the consent gates for installId and linkInstall, including that installId can be omitted and that false removes an earlier link. The description restates the true/false consent choice but adds little parameter meaning beyond that structured guidance, so the baseline score 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 specific verb and resource, "Connects this client to a CookiePal account," immediately establish the operation. The browser-authentication flow and reported user, organisation, and default-domain context distinguish it from the status-oriented whoami sibling and the domain, banner, and scan tools.

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 conditional sign-in flow and explicit consent conditions for install linking clarify how the tool is used, but tool-selection guidance remains implied. It does not say when connection is required before other tools or that whoami is preferable when the user only wants to inspect the current connection.

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 past the annotations by disclosing a side effect the agent could not otherwise predict: colour, logo and position changes queue a rebuild, that rebuild is skipped (and reported) when the domain has hit its page-view limit, and text changes go live without one. It also states the merge semantics of the update, which matters given destructiveHint=true. The annotations already flag the write/it is a write and destructive profile, so this added operational context is exactly the right supplement.

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 purpose, then the partial-update rule, then the exclusions and the rebuild caveat. The final sentence carries a dense parenthetical about the page-view limit, but it is genuinely load-bearing information rather than filler. Little could be cut without losing behaviour.

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 five-parameter nested mutation tool with an output schema present, the description covers what can change, what cannot, what happens to unspecified fields, and the asynchronous rebuild consequence with its failure condition. Nothing an agent needs to call it correctly and warn the user appropriately appears to be missing.

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

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

Schema description coverage is 100%, so the nested logo, texts, colors, domainId and positions objects are already documented in the schema, including locale format and per-language constraints. The description adds the meaningful nuance that texts are per-language copy for languages the banner already has and that category texts are out of scope, but it does not elaborate on field-level choices such as the position enums. 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?

"Changes how one of your CookiePal domains' banner looks and reads" gives a specific verb and resource, and the enumeration of modifiable facets (colours, logo type and colour, positions, per-language title/description/button texts) makes the scope concrete. It stops short of naming the closely related siblings (set_banner_mode, regenerate_banner), so the boundary against those is left to the agent to infer.

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?

"Give only what you want to change; everything else keeps its saved value" clearly frames this as a partial update, and the exclusion sentence routes logo uploads and category texts to the dashboard. What is missing is explicit routing against sibling tools that also touch banner state, so the agent must guess when to prefer set_banner_mode or regenerate_banner.

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 annotations, it discloses the return contract (deleted count vs. remaining count), the completion condition ('only a run reporting no remainder has finished'), re-run behavior, the empty-ID case, and the side effect of unlinking the install from a CookiePal account. That last point is a non-obvious destructive side effect not visible in 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 core is front-loaded, but the justification clause ('because once the ID is gone there is nothing left to look the checks up by') restates the same idea twice and the returned-count sentences are wordier than needed. Serviceable, not 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 destructive single-parameter tool with an output schema, the description covers what matters: irreversibility timing, idempotency semantics, empty-result behavior, and an unadvertised account side effect. Nothing an agent needs before calling 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% and the installId description already says every check under it is deleted, so the description adds essentially nothing new about the parameter. 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 ('Deletes') and a precisely scoped resource ('the checks CookiePal stored under one install ID'), which no sibling tool touches. The scope is narrow and 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?

Gives explicit timing guidance ('Run it from the plugin before the ID is removed') and a prerequisite note ('No account needed'). It doesn't name an alternative tool, but no sibling operates on install-scoped checks, so there is little to disambiguate against.

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), yet the description still adds substantive behavior: the output is byte-for-byte identical to what the dashboard copies, it includes `defer` for Shopify stores, the embedded URL is domain-specific, and a manually constructed tag will not verify. That last point is the kind of consequence disclosure an agent cannot infer from structured fields.

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

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

Three tight sentences, front-loaded with what is returned and scoped immediately to a single domain. Every sentence carries a distinct payload — identity, constraint on fidelity, and next step — 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 single-optional-parameter read tool with an output schema and full annotation coverage, nothing material is missing: the return value needn't be explained, the safety profile is annotated, and the description supplies the domain-specificity and Shopify caveats an agent would otherwise get wrong.

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

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

Schema description coverage is 100%, and the schema already explains that domainId selects a domain and that omitting it falls back to the account's default domain. The description restates the 'one domain in the connected account' scope but adds no format, validation, or lookup guidance 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?

States a specific verb and resource — 'Returns the CookiePal banner script tag' — and scopes it to 'one domain in the connected account'. It also implicitly separates itself from verify_installation (named as the follow-up check) and from regenerate_banner (a hand-built or re-generated tag is explicitly called out as not equivalent).

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 clear operating context: use this to obtain the tag to paste into a site, and run verify_installation afterwards to confirm it is live. It also warns against hand-building or cross-copying a tag. It stops short of an explicit 'do not use this when…' exclusion against siblings like regenerate_banner, so it is strong rather than complete.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world behavior, and the description still adds real value: in-flight scan handling (returns a running status rather than stale data) and an explicit scope boundary that results are findings, not a legal compliance verdict. Those are behavioral traits an agent cannot infer from annotations or schema.

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

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

Front-loaded with the core action, then the in-progress caveat, then the scope disclaimer. The sentence 'The result reports what was found' is thin on its own but serves as the lead-in to the compliance disclaimer, so waste is minimal rather than zero.

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

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

With an output schema present, return-value detail is unnecessary, and annotations carry the safety profile, so the description's remaining burden is scope and edge-case behavior, which it covers well (running scans, non-compliance semantics). Only a note on report freshness or size/coverage expectations 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?

There is a single parameter, and the schema already documents it at 100% coverage, including the omit-for-default behavior. The description adds no further meaning about domainId, so the baseline of 3 for high-coverage schemas applies.

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

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

States a specific verb and resource ('Returns the latest cookie report for one of your CookiePal domains') and enumerates the payload ('each cookie's category, and says whether it came from a local scan'). It is clearly distinguishable from siblings like start_scan or upload_scan_report, which it references by name.

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

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

Gives concrete conditional guidance: when a start_scan crawl is still running, the tool reports that state instead of returning an old report. That tells an agent the right post-start_scan timing. It stops short of explicitly stating when-not to use it or naming a preferred alternative (e.g., upload_scan_report for externally produced reports).

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 real value by disclosing the visibility scope ("that this user can see") and the per-domain plan semantics, but says nothing about result volume, pagination, or ordering for a list operation that could return many rows.

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

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

One sentence, front-loaded with the verb and resource, with the returned field list placed after the core claim. The trailing "Plans are per domain." is a slightly awkward fragment but does clarify a genuinely ambiguous point rather than padding.

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

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

With no parameters, rich annotations, and an output schema that documents the return shape, the description covers nearly everything needed to select and call the tool. The only gap is any hint about result size or whether the full domain set is always returned.

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

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

There are zero input parameters, so the baseline is 4. The description correctly implies a single-account, unfiltered listing and introduces no parameter expectations that the empty schema would contradict.

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 pairs a specific verb ("Lists") with a specific resource ("domains in the connected CookiePal account") and scopes it to what the user can see. It also enumerates the per-domain data returned, which makes it trivially distinguishable from siblings like add_domain or verify_installation.

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

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

Usage is only implied: an agent can infer this is the discovery call to enumerate domains before acting on one, but the description never says when to use it or when to prefer another tool. It also gives no prerequisites or context about account connection state.

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 that the page is loaded locally and never by CookiePal, that no account is needed, and that the tool returns a check ID plus a plan containing accept and reject banner matchers. The local-only execution requirement and 30-minute submission window provide important operational and privacy context.

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

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

The description is front-loaded with purpose, outputs, workflow, and authentication before detailing host restrictions. It is somewhat repetitive about local execution and the user's own computer, although those passages separately support privacy and compatibility constraints.

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

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

For a tool with one required parameter and an output schema, it supplies the execution model, privacy boundary, authentication requirement, next workflow step, deadline, and supported and unsupported environments. The undocumented optional pluginVersion is a minor gap that does not impede correct selection or 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?

With 67% schema coverage, url and installId are already documented, while the description adds operational context for the URL by explaining its local browser use. It does not explain pluginVersion or when that optional value should be supplied, so the schema still does most of the parameter-specific 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 opening sentence gives a specific action, resource, and scope: starting a check of one web page for cookies set before consent. The local-browser plan and pre-consent focus distinguish it from broader scanning and cookie-classification siblings without requiring their 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 explicitly requires the CookiePal plugin in Claude Code on the user's computer and identifies the supported terminal, desktop, and IDE-extension forms. It also excludes claude.ai, web-based Claude Code, cloud runs, crawlers, and other browsers, then directs the result to submit_check within 30 minutes.

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 mutation safety (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description adds genuine context beyond them: the work is queued rather than applied inline, no settings are altered, and a page-view limit can cause a no-op that is reported in the result. It stops short of auth or per-call rate details.

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

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

Three tight sentences: what it does first, then the non-mutation and single-domain constraints, then the failure mode. Every clause carries information an agent needs, and nothing is repeated from the schema.

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

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

For a one-optional-parameter queueing action with an output schema covering the return shape, the description covers purpose, scope, side-effect posture, and the one notable failure mode. Nothing an agent needs before calling it is missing.

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

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

Schema coverage is 100% and the single parameter already documents the omit-for-default-domain behavior, so the schema does the heavy lifting. The description only reinforces the constraint ('one domain only') without adding syntax or defaulting detail beyond what is already structured.

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

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

The description gives a specific verb and resource ('Queues a rebuild of the cookie banner script') scoped to 'one of your CookiePal domains', and immediately separates it from settings-mutating siblings: 'It changes no setting'. An agent can distinguish it from customise_banner or set_banner_mode without reading 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 implies the right moment to call it ('so it picks up the settings saved for it') and states a hard constraint ('works on one domain only'), but it never explicitly names the alternative tool to use when you want to change settings rather than reapply them. Clear context, no named exclusion.

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 the side effect (queues a rebuild so the change goes live), the failure mode (rebuild skipped when the domain hits its page-view limit), and that the result surfaces that condition. It also clarifies the edge-routing semantics of 'both' rather than leaving the enum opaque.

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, then the constraints and side effects; every clause carries information. It is a single long chained sentence, though, so the rebuild and page-view-limit caveats would read better as a separate 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?

With an output schema handling return shape and annotations covering idempotency and safety, the description supplies exactly the missing behavioral layer: side effects, the page-view-limit edge case, and enum semantics. Nothing needed to invoke 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 coverage is only 50%: domainId is documented in the schema but bannerMode's enum values are not explained there. The description fills that gap precisely, defining gdpr, ccpa, and 'both' as GDPR everywhere plus CCPA to US visitors at the edge, which is real added 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?

Names a specific verb (sets) and resource (which privacy regulation a CookiePal domain's banner follows), and enumerates the three modes. It is clearly separable from siblings like customise_banner or regenerate_banner, which touch other banner aspects.

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 scopes the change tightly ('changes nothing else about the banner'), which implicitly tells the agent to reach for customise_banner or regenerate_banner for other edits. It never states explicit when-not conditions or names those alternatives, so it stops short of full 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 only declare readOnly=false, destructive=false, idempotent=false and openWorld=false; the description adds substantive context beyond that — the crawl runs client-side in the CookiePal plugin on the user's machine, the server performs no crawling, the report must be uploaded separately, and the banner must be verified and active beforehand. These are prerequisites and side effects the annotations do not convey.

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 action and the follow-up step are front-loaded, and each sentence carries information. The final sentence is somewhat repetitive, restating the local-only constraint twice ('claude.ai and Claude Code on the web run in the cloud' plus 'a crawler or browser run anywhere else does not stand in for it'), which could be tightened.

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 job-starting tool with two optional parameters and an output schema, the description covers everything an agent needs: prerequisites, environment eligibility, and the next step after the crawl finishes. Return values need not be explained because an output schema exists.

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 both parameters already document their meaning, defaults and limits (domainId defaults to the account's default domain, maxPages 1–50). The description adds no syntax, format or selection guidance for either parameter, 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 — 'Starts a crawl of one of your CookiePal domains on the user's own computer' — and immediately distinguishes the tool's division of labour from siblings (upload_scan_report handles the result, get_scan_report reports status). An agent can identify what this does and what it does not do 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 explicit preconditions ('Needs the domain's banner to be verified and active first, unless this is the very first scan of a domain just added with add_domain'), names the follow-up tool (upload_scan_report) and the status-checking tool (get_scan_report), and rules out whole environments (claude.ai, Claude Code on the web, any other crawler or browser). Both when-to-use and when-not-to-use are spelled out.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false), the description discloses meaningful behavior: the call persists data and returns a categorized summary, submission is one-shot per check ID, and it carries a not-a-legal-verdict disclaimer plus a caveat that a no-banner reading is inconclusive rather than evidence. What is left unsaid is the consequence of violating the one-shot rule (rejection vs. silent overwrite) and whether any size limits cause truncation, so it falls short of a 5.

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

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

Function is front-loaded in the first sentence, then constraints follow in a deliberate order (payload rules, consent condition, region caveat, one-shot rule, environment restriction, scope disclaimer). It is dense but nearly every sentence carries a constraint; the environment paragraph is long enough that it could be tightened without losing meaning.

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

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

For a nested-object tool with an output schema present, the description covers the hard parts an agent would otherwise get wrong: provenance from plan_check, the local-only execution requirement, category assignment provenance, and the interpretation limits of a no-banner result. Remaining gaps are the meaning of thirdPartyHosts and behavior on a duplicate submission.

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 only 50% schema description coverage, the description does real work: it enumerates the six category values, states that cookies carry attributes but never their value, and explains that consent should be included only when accept and reject were actually pressed. It does not explain thirdPartyHosts, resultVersion, or truncated, so half the top-level surface remains undocumented in prose.

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 a specific verb and resource ('Stores the result of a local check started with plan_check') and adds what it returns ('a summary by category'). It names the sibling tool plan_check that produces the input, so the agent can place it in the workflow 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 explicit preconditions and exclusions: the local run must come from the CookiePal plugin on the user's own machine (terminal, desktop app, IDE), and claude.ai, Claude Code on the web, or any other crawler/browser run does not satisfy it. It also states per-check cardinality ('Each check ID can be submitted once') and the condition for including consent, which are exactly the conditions an agent needs to decide whether it may call this at all.

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 non-read-only, non-idempotent, non-destructive, closed-world, so the safety profile is partly covered; the description adds real value on top by disclosing that a second upload of the same scan ID is rejected, that a robots-blocked submission stores nothing, and that the stored result is descriptive rather than a compliance verdict. It does not describe failure modes for malformed cookie payloads or what happens to partial uploads, which keeps it below a 5.

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

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

Front-loaded with the core action and the robots.txt edge case before the environment caveat, and each sentence carries a distinct constraint. The environment paragraph is somewhat long-winded and restates the same point (local-only) three ways, which costs a little density.

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

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

An output schema exists, so return values need not be explained; what matters is covered — provenance of the crawl, the robots.txt branch, the one-upload rule, and the non-verdict framing. The remaining gap is the unexplained truncated/pagesScanned/thirdPartyHosts fields and any guidance on partial or failed submissions.

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% across six parameters, so the description must compensate. It explains the meaningful ones well — cookies must carry the category assigned from @cookiepal-oss/cookie-db, and blockedByRobots suppresses storage — but truncated, pagesScanned, and thirdPartyHosts are never mentioned, leaving half the surface to inference from property names.

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 ("Stores the result of a local crawl ... as a report labelled a local scan") and anchors it to the sibling that produces the input (start_scan). An agent can immediately distinguish it from start_scan (which runs the crawl) and get_scan_report (which reads one back).

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

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

Gives explicit preconditions and exclusions: the local run must come from the CookiePal plugin in Claude Code on the user's own machine, and claude.ai, Claude Code on the web, or any other crawler/browser run does not qualify. It also names the robots.txt branch (send blockedByRobots and no report is stored) and the once-per-scan-ID limit, so the agent knows both when to call and when the call is pointless.

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 declare this is a non-read-only, non-idempotent, non-destructive, closed-world write, and the description adds real behavior beyond that: the server compares the page's banner script against the domain's expected tag, mismatches end as failed with a reason, and the result is not a compliance verdict. It does not cover repeat-call or status-overwrite consequences, which is why it is not a 5.

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

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

Front-loaded with what gets recorded and what changes, then the local-run precondition, then scope limits. Slightly redundant, since 'CookiePal never requests the page' and 'Nothing is crawled on CookiePal's side' say the same thing twice.

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 an output schema exists, the description need not describe return shape; it still explains the outcome semantics (verified/failed with reason, not a compliance verdict) and the unusual local-execution constraint. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is already 100%, so the baseline is 3; the description earns more by insisting the evidence object be sent exactly as the local verify step returned it and never assembled or edited, and by clarifying the server, not the caller, judges the scriptSrc. domainId handling (omit for the default domain) is left to 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 verb and resource: records a check of one domain's live page and sets that domain's banner verification status to verified or failed. It is clearly distinguishable from scanning/crawling siblings because it explicitly says nothing is crawled server-side and the page load must come from the user's machine.

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

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

Explicitly names the required precondition (load the page locally first and send what it found) and rules out the alternatives: claude.ai, Claude Code on the web, and crawlers or browsers elsewhere cannot stand in. That is an unusually complete when-to-use and when-not-to-use statement.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered upstream. The description adds that plan and page-view-limit state are surfaced, but that is largely return-content information already carried by the output schema. No auth/permission requirements or failure behavior (e.g., unconnected client) are described, so added behavioral value is modest.

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

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

Two sentences, front-loaded with the core purpose followed by usage triggers. The enumeration of reported fields is dense but every item earns its place by telling the agent what context it gains from calling.

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

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

With an output schema present, return-value explanation is not required, and annotations cover the safety profile; the description supplies purpose and usage triggers for a one-parameter tool. It is nearly complete, though a note on the unconnected/no-domain case would close the last gap.

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

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

Schema description coverage is 100%; the single optional `domain` parameter is fully documented in the schema, including its default. The description's mention of "which domain other tools will use when none is given" reinforces the defaulting behavior but adds no syntax or constraint detail beyond the schema. Baseline 3 applies.

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

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

Uses a specific verb ("Reports") plus a concrete resource (the signed-in CookiePal account) and enumerates what that includes: user, organisation, default domain, and each domain's plan and page-view limit status. An agent can distinguish this from siblings like list_domains or plan_check because it describes reporting the identity/default context rather than enumerating or checking a specific plan.

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 two explicit triggers: "Use it to confirm a connection, or to find out which domain other tools will use when none is given." That covers the main when-to-use cases well. It doesn't name alternatives (e.g., list_domains for full domain enumeration) or state when not to use it, so it stops short of a 5.

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