Cromanion

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

The idempotentHint annotation is reinforced and detailed by the description: 'the same matcher twice creates one goal.' The description also discloses mutation behavior for existing goals, removal semantics, and the permissions requirement. It is consistent with destructiveHint=false because removing a goal is described as 'stop counting it' rather than destroying historical data.

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

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

The core verb and resource are front-loaded, and the create/edit/remove modes are each stated in compact, purposeful sentences. The conceptual warning about pageview-level goals earns its place because it prevents a common misuse of the tool. There is no filler or redundant restatement of schema fields.

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 the 8-parameter schema and 100% coverage, the description supplies the missing combination rules and permission context that the schema alone does not make explicit. It also warns about low-value goals, which matters for the agent's decision-making. The output schema exists, so the description does not need to explain return values.

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?

Even though schema description coverage is 100%, the description adds relationship semantics beyond individual property docs: `type` and `value` together define a new matcher, `goalId` switches to modification mode, and `goalId` with `remove: true` means stop counting. It also maps 'rename, reprioritise or price' to label, priority, and dollarValue, which helps an agent combine parameters correctly.

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 'Define a conversion to count, or change one you already defined,' naming a specific resource and both creation and modification behaviors. It also contrasts the tool with 'one more setting,' which helps distinguish it from the cromanion_set_* sibling family. This is far more than a restatement of the tool 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?

The description clearly explains the two operational modes: send `type` and `value` to create, or send `goalId` to rename, reprioritise, price, or remove an existing goal. It also states the goals permission prerequisite. It does not explicitly name sibling alternatives or exclusion conditions, but the 'not one more setting' warning provides useful context for when this tool is appropriate.

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, the description adds real behavioral context: the challenge-publishing requirement for new domains, the asymmetry between owned and new domains, the refusal behavior for restricted credentials, and an explicit permission requirement. These are meaningful for safe invocation and are not present 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 main action is front-loaded and the conditions are ordered logically. It is a bit dense and stylized ('CREATING one does', 'nothing about holding a credential for one domain says anything about another'), but each sentence adds a distinct piece of information, so it earns its place.

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

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

The description covers the tricky edge cases: already-owned versus newly created sites, restricted credentials, permission requirements, and the plan limitation. Since an output schema exists, return-value details are not needed. This is complete for a mutating tool with meaningful behavioral caveats.

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 explains both parameters well, including when siteId is needed and what siteUrl expects. The description adds no parameter-specific meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Add another of your human's sites to their account,' and narrows the scope with 'on a plan that allows more than one.' It clearly distinguishes the tool from siblings like add_goal or ask_human by describing what it adds and when proof is needed.

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 tells the agent when no proof is needed (already-owned sites), when proof is required (creating a new site), and when the call is refused (restricted credential), naming cromanion_ask_human as the alternative. It also states the required site-config permission, giving clear invocation conditions.

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 adds substantial behavioral context beyond the annotations: the request appears on the human's notification screen, is attributed to the agent, receives no inline reply, and replaces a prior request rather than stacking. It also tells the agent to re-read cromanion_grants or cromanion_config to see the outcome, which is essential for this async 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?

The first sentence states the purpose immediately, and subsequent sentences explain when to use it, what happens after invocation, and the rate limiting. It is slightly rhetorical in the middle, but every sentence contributes useful decision-making or behavioral 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 an unusual asynchronous human-interaction tool, the description is complete: it explains the delivery channel, attribution, lack of inline response, how to observe the result, and the request rate limit. The output schema exists, and the description correctly tells the agent not to expect a direct reply.

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 each parameter already has a meaningful description. The tool description does not add parameter-specific semantics, so the baseline score 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 concrete action and resource: asking the human for something only they can do, delivered to their notifications screen. It also distinguishes this tool from the broader refusal/error path in sibling tools by contrasting permission, payment, and mode blocks that otherwise end with the agent reading the result.

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 applicable scenarios: human-only actions like granting permissions, making payments, or setting modes that the agent cannot perform. It also explains follow-up behavior, the one-request-per-hour limit, and replacement semantics, though it does not explicitly list alternative sibling tools by 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?

The description goes well beyond the annotations by disclosing the site-config permission requirement, the challenge-publication workflow, and the subdomain-coverage behavior. It also reinforces the destructive nature of removal ('give one up') consistent with destructiveHint=true.

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 primary action and effect, followed by the key caveat and exclusion. Every sentence earns its place and there is no redundant restating of schema fields.

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 an output schema and fully described parameters, the description covers the critical operational context: permission needed, challenge requirement for new registrable domains, and the subdomain no-op rule. 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 coverage is 100%, so the baseline is 3. The description adds value by clarifying that the domain must be a different registrable domain and that subdomains are already covered without a call, enriching the meaning of the domain parameter beyond the schema's simple hostname example.

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 action ('Claim another host for this site so its traffic counts') and the inverse action ('give one up with remove: true'), clearly identifying the resource and effect. It also distinguishes itself from related claim/verification work by noting subdomains need no call, so an agent can tell what this tool is for.

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 when-to-use context ('so its traffic counts'), an explicit when-not-to-use rule ('Subdomains need no call at all'), and the proof workflow for a different registrable domain. It does not name sibling tools like cromanion_verify_claim as alternatives, but the process is concrete enough to guide selection.

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. The description adds valuable context: this tool reflects already-decided state, including the caller's own decisions, and warns that writes on the site replace rather than add. This goes beyond the annotation without contradicting 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?

Three front-loaded sentences deliver the core purpose, a category list, the sibling alternative, and a usage warning. The enumeration is slightly dense but each sentence earns its place; no filler or repetition of schema content.

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 one optional parameter and an output schema, the description fully covers purpose, scope, sibling relationship, and when to invoke it. 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 description coverage is 100%, and the siteId parameter is already thoroughly documented, even cross-referencing cromanion_grants and explaining the refusal behavior when omitted. The free-text description adds no parameter-specific 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 clear read purpose — showing everything 'in force' on a site — and enumerates the content categories (conversions, allowed/forbidden facts, surfaces, brand, rule statuses). It explicitly distinguishes itself from cromanion_pending, which shows undecided items, so an agent can tell this tool apart from its 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 gives an explicit when-to-use rule ('Read it before writing anything') and names the alternative for pending decisions (cromanion_pending). The warning that most writes replace rather than add reinforces why consulting this tool first matters, leaving no ambiguity about its role.

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, openWorldHint=true, idempotentHint=false), the description discloses two non-obvious operational constraints not visible in structured data: 'one crawl per 30 minutes' rate limiting and the 'site-config permission' requirement. It also frames the call's effect as improving the agent's site understanding. No contradiction with annotations — a crawl with side effects is consistent with readOnlyHint=false.

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 and closing with hard constraints (rate limit, permission). The second sentence's motivational aside, 'You know this site's structure better than its owner does,' is mild fluff, though the 'cheapest real improvement' clause does add a usage signal. Slightly compressible but well under the size limit and mostly earning its place.

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

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

For a 2-parameter, fully-schema-documented tool with an output schema and four annotations, the description covers the operational essentials an agent needs to invoke it correctly: purpose, rate limiting, and required permission. Output schema handles return values, annotations handle IDempotency/destructiveness. The remaining gap is strategic (when to crawl) rather than mechanical, so nothing critical 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 schema descriptions are exceptional: siteId explains when it's required, points to cromanion_grants, and states the refusal-on-omission behavior; priorityUrls documents the 10-item limit, path/URL format with examples, and the 'handed back rather than dropped' error handling. The main description only loosely gestures at priorityUrls ('name the pages that matter most'), so the schema carries the burden — 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 a specific action and resource: 'Re-read the site' (crawl the site) with a clear behavioral add-on, 'name the pages that matter most so they are read first' (priority seeding). The title annotation reinforces this. Among 24 siblings, none is an obvious crawl alternative, so no explicit differentiation is needed, though the verb 're-read' is slightly indirect for 'crawl'.

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 context is implied: 'seeding it is the cheapest real improvement to what the agent understands' suggests this is the go-to refresh mechanism, and the rate limit warns against frequent calls. However, the description never states when to use it (initial setup, after site changes, periodically), names no alternative tools, and gives no when-not-to-use guidance. The guidance is implied rather than explicit.

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

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

Discloses the consequential, permanent semantic effect of approving a GOAL — that it changes what every impact figure for this site means. Also clarifies that the decision is a status only, not editable rule text, adding real behavioral context beyond 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?

Four dense, purposeful sentences with the core instruction front-loaded. Each sentence earns its place: what to pass, which decisions apply to what, the critical GOAL caveat, and the edit limitation. No filler or repetition.

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

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

Completeness is achieved given the output schema and rich parameter descriptions. The description covers the call pattern, decision applicability, the most important semantic consequence, and the boundary with sibling tools, so an agent has enough to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by warning that approving a GOAL permanently changes impact figures and by emphasizing that kind and id must be passed back unchanged. This is useful but not required for every 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?

States a specific action — 'Rule on one thing from cromanion_pending' — and enumerates the exact decision values. It also distinguishes itself from rule-text editing by saying 'You cannot edit rule text here, only rule on it,' which separates it from cromanion_set_playbook.

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 clear scope: approve/reject apply to everything, pause applies only to playbook_rule, and rule text must not be edited here. It implies the alternative (edit via cromanion_set_playbook) through the negative constraint but does not explicitly name it in the description.

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 signal destructive and non-read-only behavior, but the description adds meaningful context: it requires the integrations permission, fails when any site still delivers to HubSpot, and has the serious side effect that forms would keep working while every lead delivery fails. It also makes the irreversible nature concrete by explaining that reconnection is a human-only OAuth consent screen. This goes well beyond the annotations and does not contradict them.

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 dense but well structured: the core action comes first, followed by the relation to a sibling, a critical refusal condition, the one-way nature, and the permission requirement. Each sentence earns its place and no filler is present.

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 prerequisites, preconditions, failure modes, side effects, irreversibility, and the alternative path through cromanion_set_lead_destination. Since an output schema exists, the lack of return-value detail is not a gap. The agent has enough context to decide correctly whether and when to invoke this tool.

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

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

The only parameter, siteId, already has 100% schema documentation, including when it is required and that it is refused if omitted when multiple sites are covered. The tool description itself adds no additional parameter-level 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 immediately states the specific action: 'Sever the account's HubSpot connection.' It also distinguishes itself from siblings by naming itself as 'the other half of cromanion_set_lead_destination's `hubspot` option,' so an agent can clearly tell what this tool does and how it differs.

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 explicitly explains when the tool is appropriate: it is the counterpart to setting a HubSpot destination and should be used to remove leads from a CRM. It also gives a clear precondition and exclusion — disconnection is refused while any site still delivers to HubSpot, and the user should change those destinations first. It further warns that reconnection is not a tool action but a human-only OAuth flow, so the agent should treat this as one-way and communicate that before calling.

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 mark readOnlyHint=true, and the description adds valuable context beyond that: it reveals the credential-free access ('Needs no credential') and explains the semantic of the `retry` field with three enumerated values (`later`, `fix_request`, `needs_human`) and what each implies. This is behavioral disclosure that helps an agent interpret the output without guessing.

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 four sentences, front-loaded with the core purpose, then the credential note, then the retry-field explanation, and a closing recommendation. Every sentence adds value; there is no fluff 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?

For a read-only, parameterless tool with an output schema, the description covers the essential context: what it returns (all refusals), how to use it (without credentials, even after a refusal), and how to interpret the key field. The output schema presumably details the structure, so the description doesn't need to list every refusal. It is complete for an agent to decide when to call and how to act on the response.

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 and the schema is an empty object, so the description has no parameters to document. The baseline for 0 params is 4, and the description correctly focuses on output semantics instead. No gaps exist in parameter documentation.

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 precise statement: 'Every refusal this server can return, and what to do about each.' This identifies a specific resource (the catalog of refusals) and its purpose (guidance on handling each), distinguishing it from sibling action-oriented tools. The verb 'read' is implicit but clear, and 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?

The description explicitly states when to use it: 'Needs no credential — you can read it before you have one, or after a refusal has told you the one you had is gone.' It also advises 'Read it once and stop guessing whether a 409 is worth retrying,' which guides agents to consult it for retry decisions. It doesn't name alternatives, but as a unique reference tool the context is sufficient.

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 and openWorldHint; the description reinforces this by stating 'You cannot change these yourself; only your human can, in their console.' This adds ownership and mutability context beyond the structured fields, though it doesn't describe the output format, which is covered by the output schema.

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

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

Three short sentences lead with the core purpose, then a usage warning, then a mutability constraint. No filler; each sentence contributes new 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 parameters, a readOnlyHint annotation, and an output schema present, the description covers what the tool lists, when to read it, and how permissions can change. Nothing needed for correct invocation 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 and schema coverage is 100%, so the description needs no parameter detail. The baseline for zero-parameter tools is 4.

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 ('List') and a specific resource ('what your human has allowed this agent to do, and what they have not'), clearly identifying it as a permission introspection tool. This distinguishes it from sibling action tools like cromanion_add_goal and cromanion_decide.

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 instructs the agent to 'Read this before assuming a capability' and warns that the alternative is 'discovering your permissions by failing in front of them,' which tells when to use it. It doesn't name sibling exclusions, but no sibling offers the same read-only permission list, so the context is sufficient.

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 readOnlyHint annotation, the description discloses the critical interpretive nuance that `learn` and `insufficient` statuses do not mean 'no lift', and explains the holdout control design. This prevents misinterpretation of results and reveals behavior around inconclusive or not-yet-shown data. No contradiction with annotations exists.

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 each carry essential information: what the tool measures, the prerequisite status check, and the meaning of ambiguous statuses. It is appropriately sized with no filler, though the opening noun phrase could have been phrased as a clear verb statement for quicker parsing.

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 low-complexity, read-only tool with one optional parameter and an output schema, the description provides the key interpretive context needed to correctly use the result. It explains the control group and how to read liftStatus, which is sufficient for most agents. It stops short of describing all possible status values or how to interpret a true 'no lift' result, but the output schema can fill that 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?

Input schema coverage is 100%, and the schema already fully documents siteId including when it's required and the consequence of omitting it. The description adds no parameter-specific detail, so the baseline 3 applies; the schema carries the semantic load.

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 clarifies that the tool reports the effect of what the agent changed, comparing visitors who saw it against a 10% holdout control. Though it lacks an explicit verb like 'read', the annotation title supplies 'Read measured lift against the holdout', making the purpose clear. It doesn't explicitly distinguish itself from siblings like cromanion_site_status or cromanion_surfaces, but the experimental lift framing sets it apart.

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 gives clear workflow guidance: read `liftStatus` before reporting anything, and explains that `learn` and `insufficient` are not 'no lift'. However, it provides no explicit comparison to alternatives or when not to use this tool, so usage context is implied rather than fully 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?

Even though readOnlyHint=true already signals a read-only operation, the description adds meaningful behavioral context beyond annotations: it fetches ten pages from the human's server, is rate-limited to one check every two minutes, reports per page, identifies four specific failure modes, and includes fixes. This is exactly the kind of side-effect and constraint disclosure 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?

The description is dense but every sentence earns its place: it establishes the relationship to site_status, lists the four diagnostic categories, promises fixes, and discloses the rate limit and page-fetch behavior. It is front-loaded with the core purpose and contains no filler or repetition.

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

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

For a diagnostic tool with a single optional parameter, a rich output schema, and annotations declaring read-only and open-world behavior, the description is complete. It covers when to use it, what it checks, what it returns, and the operational constraint of rate-limiting, leaving no critical gap for an agent deciding whether or how to invoke it.

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 input schema already fully describes the single `siteId` parameter, including when it is required and what happens if omitted with multiple credentials. Because schema description coverage is 100%, the description does not need to add parameter semantics; 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 clearly states the tool's purpose: diagnosing why the tag is not firing, and explicitly contrasts it with cromanion_site_status, which only reports `verified: false`. It names the resource (the human's pages) and the specific output (per-page tag presence and blockers), making it impossible to confuse with 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?

The description gives an explicit when-to-use trigger: when cromanion_site_status reports `verified: false`, this tool explains why. It also names the alternative tool and the four diagnostic categories it covers, giving an agent clear grounds for choosing this tool over cromanion_site_status or other 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 already mark this as non-read-only, idempotent, and non-destructive; the description adds useful context on permission requirements and the 'one notification or all' side effect. It also explains the operational problem it solves. It does not specify the output shape, but an output schema exists to cover that.

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 compact and front-loaded: purpose, then motivation, then invocation options and permission. The 'queue grew for ever' sentence earns its place by explaining why the tool exists, and there is no filler.

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

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

With two optional parameters, full schema descriptions, an output schema, and annotations covering idempotence/destructiveness, the description supplies the missing operational context: when to mark, which permission is needed, and how to choose one-or-all. 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?

Both parameters are already fully documented in the input schema (siteId disambiguation and notificationId semantics incl. omit-to-clear-all), so schema coverage is 100%. The description's parameter guidance mostly restates what the schema already says, so it adds little beyond the 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 names the exact operation and object ('Mark notifications read') and adds a concrete triggering condition ('once you have passed them on to your human'). It also draws a clear line against cromanion_pending: that tool returns unread notifications, while this one clears 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 states when to use the tool, why it is needed (otherwise the queue grows and items are re-read), and a required permission ('Needs the decisions permission'). It stops short of an explicit when-not-to-use list, but the context is clear enough for an agent to choose it 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?

The description goes well beyond annotations: it states no credential is needed, no account/key/charge is created, the secret is shown only once, and the call refuses for already-registered addresses. It also explains the trust model behind the challenge, giving the agent accurate expectations about side effects and auth. No contradiction with readOnlyHint=false exists because 'creates NOTHING' is qualified as no account, key, or charge.

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 'Start here' and nearly every sentence adds behavioral or usage value, but it is slightly verbose: 'no API key, no human' and 'takes no credential' are redundant, and the trust-model sentence is explanatory rather than invocation-critical. Still well-structured for a security-sensitive flow.

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 the output schema exists and the input schema is fully covered, the description provides everything else an agent needs: prerequisites, side-effect profile, what the returned challenge/secret are for, the one-time display warning, and the already-has-account refusal condition. Nothing important 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 the input schema already documents email, siteUrl, and agent. The description only loosely reinforces that email is the login and siteUrl is the site the user controls, adding no new syntax, constraints, or format details beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with 'Start here' and clearly identifies the tool as the entry point for a Cromanion signup: it returns a challenge and a one-time secret for proving site control. It also distinguishes itself from later verification steps by describing the challenge-then-proof flow, so an agent can tell it apart from siblings like cromanion_verify_claim.

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?

'Start here' gives explicit when-to-use context, and the description states there is no API key or human needed and that the call refuses if the email already has an account. It does not name sibling alternatives explicitly, but the entry-point positioning and failure condition provide clear usage 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?

readOnlyHint=true already covers the safety profile, so the bar is lower; the description adds genuine behavioral context by aggregating all decision-pending item types into one unified view and characterizing it as the client's main console job, which an agent would not infer from annotations alone. It does not cover operational details like pagination or ordering, but the presence of an output schema offsets that.

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 with no filler: the core scope is front-loaded, the category list earns its length by concretely defining what 'pending' means, and the closing sentence efficiently points at the decision tool. The middle framing sentence ('client's actual job...') is mildly redundant with the 'one call' idea but adds workflow-priority value.

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, zero-required read-only list tool with an output schema and a fully documented parameter, nothing an agent needs to call it correctly is missing. The description covers what items appear, the site scoping, and the follow-up action, while the schema handles credential-based site selection and the output schema handles return values.

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 siteId parameter is already thoroughly documented in the schema, including when it is needed (multi-credential cases) and the refusal behavior when omitted. The description adds no parameter-level 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 opens with a specific verb and resource — 'Everything on this site that is waiting for a decision' — and enumerates four concrete categories (page rewrites, distilled rules, unconverted conversions, crawl-missed pages), making the tool's scope unmistakable. It differentiates from siblings by naming cromanion_decide as the companion action, and the annotation title 'List everything awaiting a decision' reinforces the same purpose.

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 frames this as 'the client's actual job in the console, in one call,' signaling it is the primary entry point for the review workflow, and explicitly routes the next step to cromanion_decide ('Rule on an item with cromanion_decide'). It stops short of explicitly stating when not to use alternatives among the 23 siblings, so it earns a 4 rather than 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, it discloses that the operation is cosmetic, that it affects appearance only and not what the agent may say, and that it requires the brand permission. It also explains where current guesses come from ('The crawl guesses these from a stylesheet'), adding useful behavioral context 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?

Three sentences with no filler: purpose is front-loaded, the cosmetic-only boundary is stated early, and the permission requirement is included. Every sentence contributes either to correct tool selection or safe invocation.

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 seven parameters, a nested object, and an output schema, the description supplies the missing non-schema context: why the tool exists, when to use it, its scope boundary, and required permission. The schema covers parameters and the output schema covers return values, so nothing critical 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 the input schema already documents each parameter. The description adds general context about real tokens versus crawl guesses, but it does not add per-parameter 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 a specific verb and resource: 'Adjust the palette, fonts and button styling the agent paints its surfaces with.' It also differentiates itself by declaring 'Cosmetic only — it changes how the agent looks, never what it may say,' which clearly separates it from content-affecting siblings like cromanion_set_voice and cromanion_set_playbook.

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 clear use context: the crawl guesses styling from a stylesheet, so this tool should be used when the agent knows the real tokens. It also provides an explicit exclusion ('never what it may say') and a permission prerequisite, but it does not name specific sibling alternatives to route to for content changes.

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 adds behavioral context beyond the destructive and idempotent annotations by explaining the limitation that you cannot add an exclusion (which names the caller's own browser) and the permission requirement. This reveals constraints and side effects that are not fully captured by the annotations alone.

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 concise, consisting of just a few sentences that cover purpose, limitations, and permissions without any fluff or repetition. Each sentence adds valuable information, and the structure is logical and easy to scan.

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 the tool's simplicity and the presence of an output schema, the description provides all necessary context: what the tool does, when to use it, its constraints, and its permission requirements. Nothing essential is missing for an agent to correctly invoke it.

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?

Both parameters are described with meaningful, user-oriented explanations. The label is defined as the human-given device label, and siteId is explained with its conditional necessity. These descriptions go beyond mere type info and clarify the intended use, which justifies a score above the baseline for full schema coverage.

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

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

The description clearly states the tool's purpose: to remove an exclusion and put a device back into measurement. It also provides helpful context about what exclusions are and explicitly contrasts with adding an exclusion, making the purpose 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?

The description gives practical usage guidance by stating that adding an exclusion is not possible with this tool and by mentioning the required measurement permission. It does not explicitly enumerate alternative sibling tools, but the contrast with ADD and the permission note serve as clear usage instructions.

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 indicate destructive and idempotent behavior; the description adds meaningful context about splitting the measurement window and never pooling periods. It does not repeat the destructive hint, but the annotations cover that risk.

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 concise sentences, no filler, with the primary action and key constraints stated upfront.

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?

Includes the required permission, the quantitative range, the behavioral implication of changing the value, and references an output schema exists. No critical information needed to invoke 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?

Schema covers 100% of parameters with clear descriptions; the tool description adds context about the allowed range and the measurement-window effect, but does not substantially deepen parameter-specific meaning 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 verb ('Set'), the resource ('share of visitors held back'), and the purpose ('so its effect stays measurable'), clearly distinguishing it 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?

Provides clear context about when this tool is relevant, including the required permission ('Needs the measurement permission') and the behavioral consequence of changing the holdout share. It does not explicitly contrast with alternatives, but the context is sufficient.

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: this change 'leaves no other trace' while forms keep working, every change emails the human and appears on a notifications screen, and the integrations permission is required. These side-effect, notification, and authorization details directly complement the destructiveHint=true and openWorldHint=true annotations rather than repeating them.

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 purpose in the first sentence, followed by a dense but valuable warning sentence about traceability, notifications, and permissions. Slightly long, but every clause earns its place given the destructive and silent nature of the operation.

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?

Well covered for a destructive mutation: safety profile is in annotations, all parameters are fully documented in the schema, an output schema exists, and the description adds auth requirements and side-effect disclosure. The only gap is the lack of explicit routing to or away from sibling tools such as disconnect_hubspot.

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 itself is already rich, documenting each enum value, the conditional need for target, and siteId's multi-credential refusal behavior. The description's mention of the three delivery options maps to the kind enum but adds no parameter-level semantics beyond what the schema provides, 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?

Opens with a specific verb-resource pair ('Set where captured leads are delivered') and enumerates the three delivery modes (webhook, HubSpot portal, off), which differentiates it from siblings like set_brand, set_mode, and set_voice that target different resources. An agent can tell what this tool 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 context is implied by the clear purpose and the note about needing the integrations permission, but the description never explicitly says when to choose this over alternatives or when not to use it. It does not, for example, clarify how this relates to disconnect_hubspot or when setting kind=off is preferable to disconnecting the portal.

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 adds meaningful behavioral context beyond the annotations: it explains that `learn` shows visitors nothing, that `act` acts in the user's name, and that `shadow` only proposes changes without showing them. It also discloses the activation permission requirement. This complements the annotations rather than contradicting them, though it does not go into reversibility or failure behavior.

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 three sentences with no filler. It front-loads the main action, defines both mode axes compactly, and ends with the permission requirement. Every sentence earns its place, and the density is appropriate for the complexity of 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?

Given the tool's three optional parameters, full schema coverage, annotations, and an output schema, the description is nearly complete. It communicates the core operational states, the separate customization axis, and a required permission. It could be more explicit about how to verify or obtain the activation permission, but the essential invocation context 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 100%, so the schema already documents all three parameters thoroughly. The description largely restates the mode enum meanings and introduces the "separate axis" framing, which helps conceptual understanding. However, it adds little about `siteId` or parameter-specific behavior beyond what the schema provides.

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 concrete action, "Switch the agent on," and immediately defines what each mode does: `learn` watches without showing visitors anything, while `act` lets the agent intervene. It also introduces `customizeMode` as a separate axis with three clear values. This makes the tool's purpose and scope easy to distinguish from sibling configuration tools like cromanion_set_brand or cromanion_set_voice.

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 gives a useful prerequisite, "Needs the activation permission," which tells the agent an important precondition. However, it does not explicitly name alternatives or say when not to use this tool versus a sibling such as cromanion_grants or cromanion_config. The usage context is implied by the mode definitions, but explicit routing guidance is missing.

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 carry readOnlyHint=false and destructiveHint=true, and the description is consistent with them rather than repeating them. It adds genuine behavioral context beyond the annotations: rewording 'changes what they SAY', redistilled rules 'arrive as proposed for you to rule on', the hourly rate limit, and the 'decisions permission' requirement. It does not elaborate on what exactly gets destroyed or whether a reword is reversible, but the added context is substantial.

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 dense but efficient paragraph that front-loads the core purpose before moving to modes and constraints. The background sentence explaining rules and cromanion_decide's role earns its place because it defines domain vocabulary used throughout, and the rate-limit/permission sentences are brief. It could be marginally tighter, but no sentence 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-mode tool with 5 parameters, the description covers purpose, mode selection, parameter combinations, the source of ids, the rate limit, and the permission requirement — and an output schema exists, so return values don't need explanation. The only gap is the unelaborated destructive hint: the description doesn't say whether rewording an approved rule re-enters the proposed state or permanently overwrites it, which would strengthen completeness for a destructive call.

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 with the schema doing the heavy lifting. The description adds value on top by specifying parameter interactions not in the schema: the mutually exclusive relationship between redistill and ruleId ('Send redistill: true instead'), and the combinability of ruleId with condition and/or recommendedAction. This interaction guidance is exactly what an agent needs to invoke the two modes correctly.

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 dual-purpose statement — 'Reword a distilled rule, or ask for a fresh distillation' — with a clear verb and resource, and then defines what a rule is and how it relates to siblings (cromanion_decide approves/pauses, cromanion_config provides ids). It distinguishes both modes from one another and from the sibling tools' responsibilities, so an agent can tell exactly what this tool does.

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 gives explicit conditions for each mode: send a ruleId with condition and/or recommendedAction to reword, send redistill: true to distil fresh rules, and states that ids come from cromanion_config while approval happens in cromanion_decide. It also discloses the rate limit ('one distillation an hour') and the required permission. It stops short of an explicit 'use X instead' exclusion statement, but the routing to siblings is clear enough.

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 discloses a key behavioral trait beyond the annotations: it states that markup and CSS are re-checked against an allowlist on every visitor and that anything that could run or fetch remote resources is silently removed. This warns the agent that the output may differ from the input, which is not indicated by the annotations alone.

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 somewhat repetitive and uses a quirky phrasing ('Choose where the agent may speak' and 'compare what comes back with what you sent') that could be streamlined. It is still understandable but contains redundant words and concepts that could be expressed more tightly.

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 gives enough context for the agent to use the tool effectively: it mentions the permission requirement, the filtering behavior, and the need to compare output. It does not describe the return structure since an output schema is present, which is acceptable. The overall context is sufficient for the tool's 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?

The schema already provides coverage for all five parameters, and the description adds extra semantic detail such as 'an empty string clears it' for customCss, the placeholder variables for templates, and the default off state for allowModal. This enriches the parameter meaning beyond the raw 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 clearly states the tool's function: configuring where the agent may speak (surfaces), enabling/disabling the exit modal, and setting custom CSS and per-surface HTML. It distinguishes itself from siblings by focusing on surface layout and appearance rather than other configuration aspects like goals, brands, or voice.

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 provides explicit guidance: it requires the 'surfaces' permission and instructs the agent to compare the returned data with what was sent because allowlisting may silently remove content. This helps the agent know when to use this tool and what to expect, though it does not explicitly contrast with sibling tools.

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

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

Beyond the destructive and idempotent hints, the description discloses that ungrounded rules are silently dropped, that each line is attributed to the human, that an empty string clears the voice, and that replacement is full rather than additive. It also calls out the required voice permission and that the returned lines show what survived. This is rich behavioral context beyond 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 description is dense but every sentence earns its place: purpose, line syntax, attribution, validation/drop behavior, output meaning, and permission. It is front-loaded with the core purpose before the mechanics.

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, idempotent write operation with an output schema, the description fully covers purpose, input format, side effects, error behavior (refusal to guess), permissions, and how to read the result. 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?

Despite 100% schema coverage, the description substantially enriches both parameters: text gets a line format with 'never' prefixes and empty-string clearing semantics, while siteId gets a clear rule about when it is required and that omission with multiple credentials is refused. This goes well beyond the schema's short 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?

The description opens with a specific verb and resource: 'Write the facts the agent may state to visitors, and the things it must never say,' which clearly identifies the tool as setting the agent's voice/facts. It is further clarified by the title 'Replace the facts the agent may state'. However, it does not explicitly differentiate itself from sibling set_* tools like cromanion_set_brand or cromanion_set_playbook, so it stops short of full sibling distinction.

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 provides strong how-to guidance but no explicit when-to-use or when-not-to-use guidance, and it never names an alternative tool. There is no exclusion criteria such as 'use cromanion_set_brand for brand voice instead' or prerequisite context like which other tools to prefer. This leaves selection among the many sibling set_* tools mostly 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 mark this as read-only, and the description adds meaningful behavior: the tag must be a beacon received from the caller's own domain, the call reports crawl progress and plan, and it requires the claim secret as a bearer token. This goes beyond what annotations and schema alone 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 description is three sentences with no filler, front-loading the core purpose and then giving timing and authentication requirements. Every sentence earns its place.

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

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

With an output schema present, a fully documented optional parameter, and annotations covering read-only behavior, the description supplies the remaining context: when to poll, what the verification means, and the auth requirement. Nothing essential is missing for an agent to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, and the single optional parameter siteId is already well documented, including when it is required and that omitting it with multiple credentials is refused. The tool description adds no extra parameter meaning, so the baseline of 3 is appropriate.

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

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

The description clearly states a specific verb and resource: check the site you provisioned, covering tag liveness, crawl progress, and the plan. It also distinguishes itself from related tools by defining the tag-liveness check as a beacon from your own domain rather than a handed-over snippet.

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 an explicit usage cue: 'Poll this after installing the snippet,' which tells the agent when the call applies. It does not name alternative sibling tools or state when not to use it, but the timing and prerequisite are clearly conveyed.

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, the description discloses important behavior: it returns only a URL, it does not charge the AI, the human must enter their own card, the site remains on the free plan until checkout completes, and authentication requires a claim secret as a bearer token. This is substantial behavioral context that annotations alone do not 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 description is compact and front-loaded with the tool's core purpose. Every sentence contributes: what it returns, who pays, what happens to the site during checkout, and the required auth. There is no filler or repetition of 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?

The tool is simple, has an output schema, and the description covers the two key operational facts an agent needs: the returned artifact is just a checkout URL, and auth is required via a bearer token. The schema covers plan and siteId semantics. Nothing necessary for correct invocation 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 the parameters are already well documented. The description adds little beyond what the schema provides; it mostly restates the plan options and the free-plan behavior already present in the schema. The baseline of 3 is appropriate because the description does not meaningfully compensate 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 verb and resource: 'Get a Stripe Checkout link for a paid plan (pro or growth).' It also clarifies the exact output ('Returns a URL and nothing else'), making the tool's role unmistakable and distinguishable from siblings that manage goals, claims, or site 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?

The description clearly indicates when to use the tool: when a paid plan upgrade link is needed and the human must complete checkout. It also gives an explicit guardrail — 'YOU do not pay and cannot: give the link to your human' — which is valuable usage guidance. It stops short of naming alternative tools or when not to use it, but the 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?

The annotations already cover idempotency and non-read-only behavior; the description adds valuable context by specifying that the claim secret must be a bearer token and that success creates the account/site and returns a tracking snippet. It does not contradict the annotations and provides meaningful side-effect and auth information.

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 concise, well-structured, and front-loaded with the core action. Every sentence earns its place: the precondition, the success outcome, and the idempotency/auth requirement.

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 an empty input schema and an output schema available, the description covers all essential operational context: prerequisites, proof types, auth mechanism, retry safety, and success behavior. Nothing critical 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?

With zero parameters, the schema leaves nothing to document, and the baseline is 4. The description still adds relevant input-related context by requiring the claim secret as a bearer token, which is essential for correct invocation.

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

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

The description clearly states the specific action ('redeem a claim') and the precondition ('once you have published one of its three proofs'), which distinguishes it from earlier claim-lifecycle siblings like open_claim or claim_domain. It also names the concrete outcomes: creating the account and site and returning a tracking snippet.

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 gives clear context for when to use it: after publishing a /.well-known file, meta tag, or DNS TXT record. It does not explicitly name sibling alternatives or state when not to use it, so it stops short of full exclusions.

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