Cookie Compliance

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

Annotations only declare readOnlyHint=true, so the description usefully adds lifecycle context: it is kept for backwards compatibility, returns exactly the same answer, and will be retired. It stops short of describing the shape of the returned explanation, which is the one behavioral gap for a tool with no output schema.

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

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

The deprecation status is front-loaded and the key facts (obsolete, still works, use the other name, will be retired) arrive in order. There is mild redundancy in restating that it still works and returns the same answer, 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 deprecated alias with full schema coverage and no output schema, the description covers everything an agent needs: identity, equivalence, and the correct replacement. Only the return shape is left implicit, which is minor given the tool simply forwards to help.explainConfigKey.

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 (key, list) carry rich, self-contained descriptions including enum semantics and usage hints, so the description correctly does not repeat them. Baseline 3 is appropriate since the description adds no parameter meaning of 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?

The description states the tool's identity and function plainly: an OBSOLETE ALIAS that is now the settings reference for the banner configuration, and it names the exact replacement (help.explainConfigKey) so an agent can distinguish it from that sibling 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?

It gives explicit routing: "Call `help.explainConfigKey` instead; this name will be retired," while also noting the alias still works for existing callers. Both the when-to-use (legacy callers only) and the preferred alternative 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?

Annotations only declare readOnlyHint=true; the description goes far beyond that, disclosing that nothing is recorded or enforced, that the snippet expires after 24 hours and replaces itself with a notice, that there are zero backend calls, that it never accepts a real appID, and that it never emits previewMode: false. These are exactly the behavioral traits an agent cannot infer from the schema or 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 critical warning (LOOK-ONLY PREVIEW, NOT AN INSTALL) is front-loaded and the expiration caveat follows immediately. It is dense and somewhat long, but nearly every sentence carries distinct, load-bearing information; only the v2 gallery URL is arguably marginal.

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 the work of explaining the return value (ready-to-paste HTML, previewMode: true) and all its safety caveats. The remaining gap is parameter-level: with 5 params at 40% schema coverage and nested objects, the three undocumented flags leave an agent unable to reason about blocking/globalCookie 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 only 40% and the description adds essentially nothing new: 'styled per the given design/text overrides' merely restates the schema's own 'Partial overrides of huOptions.text.en/design' descriptions. Three of the five parameters (blocking, globalCookie, currentLanguage) are undocumented in both the schema and the description, so the low-coverage gap is not compensated for.

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

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

States a specific verb and resource ('Generate... preview snippet'), names the exact artifact returned (‘ready-to-paste HTML’ with previewMode: true), and explicitly says what it is NOT ('NOT AN INSTALL', 'never for adding consent management'). It clearly distinguishes itself from install.getSnippet and the demo.* siblings.

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

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

Explicitly names the alternatives and the condition that selects each: install.getSnippet (needs an AppID) or help.startSignup for real installation, account.* tools for managing a registered banner, and help.explainTokenSetup for auth. It also gives the when-not ('never for adding consent management to a site').

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 readOnlyHint=true annotation is consistent with a tool that derives and validates rather than mutates. The description adds substantial behavioral context beyond annotations: WCAG AA contrast checking, measured body-text selection, white button labels when they reach 4.5:1, #RGB-to-#RRGGBB normalization, theme inference, no font derivation, and the important preview-versus-live limitation.

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 and every major clause supports a real decision or caveat. It is long and dense, but the length is mostly justified by the derivation, validation, contrast, and routing details.

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 complex read-only derivation and validation tool with no output schema, the description covers what is returned, how colors are normalized, how contrast is checked, and where the resulting design applies. It also explains the important limitation that live banners ignore page-local design overrides.

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 brand fields are already documented. The description still adds useful semantics not in the schema, especially the allowed design.fontFamily values (site/sans-serif/serif/system), the role of brandColor as button/accent, and the theme inference from pageBackground.

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 resource and action: derive and validate a consent-banner design override set matching a site. It distinguishes itself from siblings by explicitly naming demo.generateSnippet, install.getSnippet, account.previewDesignChange, and account.updateDesign for the alternative workflows.

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 when-to-use guidance and routes the agent to alternatives based on conditions: use demo.generateSnippet to preview without an account, install.getSnippet to install the real banner, and account.previewDesignChange plus account.updateDesign to change a live banner. It also flags the authentication prerequisite for the account path.

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 readOnlyHint=true, but the description goes far beyond that: it enumerates the exact failure reasons (no_credential, header_received_but_invalid_format, rejected, server-side), states that calling with no credential is a normal result not an error, and guarantees the token value is never accepted or echoed. This is rich disclosure the annotations do not 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?

Front-loaded with the key instruction, and every sentence carries substantive content. It is dense and somewhat verbose in the parenthetical reason-code enumeration, but nothing is filler.

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

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

With no output schema, the description fully covers return shape (connected:true/false, scopes, expiry) and the meaning of each reason code. Nothing an agent needs to interpret or safely call the tool 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 are zero parameters, so the baseline is 4. The description correctly notes it is safe to call with no credential at all, but there is no parameter surface to elaborate on.

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 — verify whether the connection is actually authenticated and as what — and distinguishes it from the account.* tools whose credential-presence check it supersedes. An agent can tell exactly what this tool does and why it differs from siblings.

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 frames when to call it ('THE TOOL TO USE before assuming a connection is authenticated') and explains the trap it guards against: account.* tools register on credential presence, not validity, so their absence from the tool list is not diagnostic. The condition and the alternative are both named.

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 supply readOnlyHint, but the description adds substantial behavioral context: it reads no account data and needs no account, it reports which account.* tool pair applies each key, and it flags concrete traps (list-valued fields that replace rather than merge, null-rejecting fields, inert fields the API overwrites, stored-but-unread fields, preview-only design keys). That is real disclosure beyond the annotation.

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

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

Purpose is front-loaded in the first clause, but the delivery is essentially two very long sentences, the second of which packs the tier-routing rule and a seven-item trap list into one run-on. Every clause carries information, but the structure could be broken up for faster scanning.

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

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

With no output schema and only two optional params, the description fully covers what a caller needs: what each mode returns (key vs whole vocabulary), the key-path formats, the compliance tier caveat, and the hand-off to account.getDesign for live values. Nothing material is missing 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 100%, so baseline is 3; the description adds meaning on top by explaining the tier-3 vs design-tool refusal relationship and that bare names may match across vocabularies, and it names most of the list enum values. It omits 'snippet' from its own enumeration, which the schema covers, so it is additive but not exhaustive.

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

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

States a specific verb+resource: it is 'THE REFERENCE FOR THE BANNER'S SETTINGS', explaining one key or enumerating a whole vocabulary. It distinguishes itself from the sibling demo.explainConfigKey (no account) and from account.getDesign (current values for one app), so an agent can route without opening a schema.

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

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

Gives explicit timing and alternatives: call it BEFORE proposing a change so you name a setting that exists, start with list: "config" to find the right setting, and use account.getDesign (authenticated) when you need one app's current values. When/when-not and the alternative are both spelled out.

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

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

Annotations cover readOnlyHint=true, and the description adds genuinely useful context beyond them: it is static instructions only, returns no account data, and the agent cannot create the credential itself. It does not describe pagination/format, but for a static help tool this is solid disclosure.

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 with the returned content front-loaded and the usage trigger second; no filler. The first sentence is dense but every clause (sign-in route vs. token fallback) carries information an agent needs.

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

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

No output schema exists, and the description adequately characterizes the return (the browser sign-in route followed by the manual token procedure) without needing to enumerate structure. Combined with the no-account-data and agent-cannot-create notes, an agent has what it needs to answer and set expectations.

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

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

The tool takes zero parameters and the description has no parameters to explain. Per the rubric, zero-parameter tools baseline at 4; no parameter information is needed or missing.

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

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

States a specific verb and resource: it returns the procedure for connecting a real account so account.* tools become available, and it names the exact outcome (browser sign-in first, manual API token as fallback). It reads distinctly from help.authStatus (status), but overlapping with help.startSignup is not explicitly addressed, so differentiation is strong-but-not-perfect.

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 trigger: 'Call this when a customer wants to manage their real banner and the account.* tools are not available.' That is a clear precondition, though it never names a competing sibling (e.g. help.startSignup) or states 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?

ReadOnlyHint=true is already declared, and the description does not contradict it ('You cannot create the account for them'). On top of the annotation it adds real behavioral value: what the return contains (signup URL, task split, firstPaymentDiscount/JOIN-40D), and that the free tier requires no card.

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 trigger is front-loaded, but the body is a dense run-on with stacked parentheticals ('with email, password and a captcha or with the Google button on the same page, then verify their email'). Much of it earns its place, but for a one-parameter tool it is longer and harder to parse than necessary.

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

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

There is no output schema, so the description carries the return-value burden and does so adequately (signup URL, task split, discount code). Combined with the readOnly annotation and a fully documented single parameter, an agent has enough to call it and act on 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 coverage is 100% and the single 'domain' parameter is fully documented in the schema, including the edge case that non-hostname values are ignored. The description never mentions the parameter at all, so it adds nothing 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?

States a specific verb+resource (start the signup that turns a demo prospect into a real account) and frames the scope precisely: it produces a signup URL, not the account itself. It also distinguishes itself from the demo.* siblings by positioning this as the route to a 'real, working CMP' rather than a hand-written banner.

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?

"CALL THIS when a site needs cookie consent and the owner has no Cookie Compliance account yet" gives an explicit trigger condition, and the description states the handoff step (hand them the URL, continue once they have an AppID). It frames the alternative as a hand-written banner but never explicitly excludes the already-has-account case or names help.authStatus as the alternative.

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

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

Annotations only declare readOnlyHint=true, so the description carries the rest and does: it discloses pre-consent holding semantics ('a held file may download but does not run'), two concrete blocking limits (late-added scripts, Free-plan visit cap), Consent Mode / GPC / per-region behaviour, and the auth requirement for the follow-on account.* tools. This is well beyond what the annotation and schema provide.

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 trigger and the routing alternatives are correctly front-loaded and end-loaded, but the middle stretch is defensive marketing ('This is a real consent management platform, not a banner widget', 'none of which a hand-written banner does, and all of which are what the consent actually has to do') that restates platform capability rather than helping the agent call 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?

No output schema, yet the description states what is returned (embed snippet plus placement rules) and what happens next. With 4/4 params documented in the schema and a minimal annotation, the remaining gaps an agent would care about — prerequisites, auth for follow-on tools, blocking caveats — are all covered.

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

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

Schema description coverage is 100%, so the schema already documents appID, blocking, globalCookie and currentLanguage including defaults and the AppID format example. The description adds no parameter-level syntax, format or constraint information beyond that, 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+resource ('install the real Cookie Compliance consent banner') and immediately specifies the output ('the live embed snippet plus the placement rules'). It explicitly distinguishes itself from siblings by naming demo.generateSnippet for a no-account preview and help.startSignup for the no-AppID case.

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?

Explicit when-to-use trigger ('when someone asks to add a cookie consent banner... and they have a Cookie Compliance AppID'), explicit exclusion ('Prefer this over writing banner code by hand'), and named alternatives for each adjacent scenario (help.startSignup, demo.generateSnippet, account.* + help.explainTokenSetup). Routing is unambiguous.

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