KANONYR publication checks

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

Annotations only carry the generic safety profile (readOnly=false, idempotent=true, destructive=false), while the description adds rich behavior: exact pricing and tax treatment, no-credits/subscription model, the required payments:schema-repair key, billing-identity and B2B-terms requirements, and the critical warning that payment credentials must never appear in arguments. This is well beyond what annotations 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?

Front-loaded with the core action and pricing, and every sentence carries substantive constraints (auth, alternative path, credential warning). It is dense and runs long as a single block, but there is little wasted text.

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

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

For a 10-required-parameter mutation tool with no output schema, the description covers pricing, gating prerequisite, auth requirements, and the alternative card flow. It stops short of describing idempotency semantics or what a successful/failed order returns, which are the main remaining gaps.

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

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

Schema description coverage is 0% across 11 parameters, so the description carries the burden and it partially compensates: it anchors locale/currency to the FR/EUR vs US/USD pricing, implies max_amount_minor=200, and explains the terms/business/professional/authority confirmations. However, inspection_id, idempotency_key, source_html_sha256 and url semantics are never clarified, leaving several parameters undocumented in both schema and prose.

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

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

States a specific verb and resource ('Buy one eligible WebPage JSON-LD correction with evidence, validation and one live check') and clearly differentiates from siblings like kanonyr_buy_technical_audit and kanonyr_verify_schema_repair. An agent immediately knows this is the paid schema-repair purchase path.

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

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

Gives an explicit prerequisite and names the sibling that gates it: 'Only buy after inspect_page reports eligible.' It also documents an alternative path ('owner may instead open card_payment_url') and a stop condition ('stop on conflicts').

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 openWorld=true, idempotent=true, destructive=false, readOnly=false, so the safety profile is covered. The description adds meaningful behavior beyond that: the exact payment prerequisites and the retry rule 'Same idempotency key and input for every retry', plus what the purchase does not include. It doesn't describe delivery mechanics or when a result becomes available.

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 compact sentences, front-loaded with price and product so the agent reads the essential facts first. The middle clauses are terse to the point of being jargon-heavy ('Explicit payments:technical-audit key', 'Stripe MPP payment'), which costs a bit of readability.

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

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

For a paid, mutating, open-world tool with 9 constrained parameters and no output schema, the description covers payment prerequisites, idempotent retry behavior, deliverable scope, and exclusions. An agent can call it correctly; only the meanings of the individual confirmation flags remain unstated.

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

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

Schema description coverage is 0% across 9 parameters, so the description carries the full explanatory burden. It partially compensates – locale/currency via the FR/EUR and US/USD pricing, idempotency_key via the retry rule, the billing-identity confirmations via 'validated ... business billing identity', and urls implicitly via '2–5 page' – but terms_accepted and authority_confirmed are never explained and the const max_amount_minor is only inferable from the stated price.

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

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

States a concrete verb and resource with scope and price: 'Buy the existing 2–5 page technical audit for EUR 5 (FR) or USD 5 (US)'. The resource ('technical audit') is clearly distinct from the sibling kanonyr_buy_schema_repair, though the description never names that sibling to make the routing explicit.

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

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

Gives preconditions for use (payments:technical-audit key, authorized Stripe MPP payment, validated FR/EUR or US/USD business billing identity) and states a scope boundary ('no remote publication or AI citation measurement') that implicitly separates it from the publication-check siblings. It stops short of explicitly naming the alternative tool to pick instead.

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

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

Beyond the annotations (openWorldHint, idempotentHint), the description discloses billing ('included, no new payment'), a retry budget (up to 3 capture attempts), the refund consequence, idempotency semantics ('same immutable evidence'), and an explicit negative scope (no ranking, indexing, JS rendering, or functionality certification). This is unusually rich operational context for a single call.

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

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

The action is front-loaded and the following sentences each carry distinct information (billing, retries, refund, idempotency, report contents, exclusions). Slight redundancy between 'included, no new payment' and the refund clause, but overall dense and purposeful.

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

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

With no output schema, the description carries the return burden and does so by enumerating what the report covers (unexpected changes, missed values, noindex, missing canonical/title, broken JSON-LD) and what it explicitly does not certify. The main omission is any explanation of the order_id input.

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

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

Schema description coverage is 0% for the single order_id parameter, and the description never mentions it or explains how it identifies the purchased baseline. With one undocumented parameter, the description fails to compensate for the schema gap.

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

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

The description states a specific verb and resource: capture the same page and compare it against the purchased baseline, triggered after the client publishes. This differentiates it from siblings like inspect_page and start_publication_check, though the exact boundary with start_publication_check is left implicit.

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 trigger ('After the client publishes') and a prerequisite (an existing purchased baseline), which implies when to call it. However, it never names an alternative tool or states an explicit when-not-to-use condition relative to kanonyr_inspect_page or kanonyr_start_publication_check.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds crucial context beyond them: that it requires the original authorized key, performs no new purchase, and is the recovery path after a lost response. These are meaningful behavioral disclosures.

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

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

Two compact sentences, front-loaded with the core action and followed by the key operational rule. No waste.

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

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

Covers the safety and recovery behavior well, but with 0% parameter coverage and no output schema, an agent still lacks detail on what the retrieved result looks like and how order_id/product map to the authorized key. Adequate but with clear gaps.

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 0%, and the description mentions 'the original authorized key' which is not a documented parameter (params are order_id and product). It does not explain order_id or product semantics, so it fails to compensate for the schema gap and introduces an undocumented key concept.

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 (retrieve) and resources (purchased result, quote or refund state), and emphasizes retrieval vs the sibling buying tools. However, it doesn't map cleanly to which sibling orders correspond, and the resource names are somewhat abstract.

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

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

Provides a concrete when-to-use rule: always retrieve before creating another order after a lost response. This directly addresses a failure mode and distinguishes it from the buy_* siblings, though it lacks explicit when-not-to-use guidance.

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

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

Annotations cover safety (readOnly, idempotent, non-destructive), so the bar is lower; the description adds genuinely non-obvious context: no account/payment/publication, a 3-requests-per-network-per-day rate limit, that unknown facts stay unknown (honest non-fabrication), and that the result_token must be kept private for purchase. It does not explain what the result actually contains.

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

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

Five short, front-loaded sentences with essentially no waste; the substantive constraints (rate limit, token handling) come after the core purpose, which is reasonable.

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, 3-param tool with no output schema, the description covers safety, free-of-charge nature, and rate limits, but omits any notion of the return value, what 'eligibility' means concretely, and documents none of its parameters.

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 0%, so the description carries the full burden, and it fails: url, idempotency_key, and locale are never mentioned. Nothing explains the locale enum (fr/en) or the uuid format/idempotency purpose, leaving all three params undocumented in both places.

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: 'one-page technical inspection and eligibility' for a 'WebPage JSON-LD repair'. It implies a two-stage funnel leading to kanonyr_buy_schema_repair but never names the sibling, so an agent must infer the connection rather than being told.

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

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

It conveys pre-purchase scoping ('free inspection', 'eligibility') and the free tier, but never explicitly says when to use this vs kanonyr_buy_technical_audit or the other kanonyr_* tools. Usage is implied by the funnel structure rather than stated.

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

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

Annotations only say this is a non-read-only, open-world, idempotent, non-destructive call; the description adds the crucial missing context: exact price (EUR 2 / USD 2, ex-tax), that it is a paid MPP charge requiring the payments:publication-check scope and validated billing, that nothing destructive happens but publication is not triggered, and a security warning not to pass payment credentials.

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 and cost, and every sentence carries information (prerequisites, sequencing, credential warning). Some clauses are dense run-ons (the pricing/scope sentence), but there is little filler.

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

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

For a paid, 10-parameter, 8-required tool with no output schema and no sibling name, the description covers pricing, auth/scopes, billing validation, the awaiting_publication hand-off, and the non-regression caveat about unlisted fields. What remains thin is the form of the result and the role of the idempotency/confirmation parameters.

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

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

Schema description coverage is 0% across 10 parameters (8 required, nested object), so the description carries the load. It meaningfully explains the `expected` object (exact desired values for the AFTER capture) and ties the price/locale/currency and the four confirmation booleans to billing and authority requirements, but leaves idempotency_key and several individual confirmation flags unaddressed.

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

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

The description gives a specific verb+resource+scope: 'Capture a paid BEFORE-publication baseline for one public HTML page.' It implicitly distinguishes itself from the AFTER/comparison step ('includes one comparison within 7 days', 'exact desired values for the AFTER capture'), but never names the sibling it is not (e.g. kanonyr_compare_publication), so an agent must infer the boundary.

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

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

It clearly frames this as the BEFORE step ('Wait for awaiting_publication before the client changes the site') and rules out alternatives ('No credits, subscription or automatic publication'), plus lists the scope and billing prerequisites. It does not explicitly state when to call the sibling comparison tool instead, leaving one inference to the agent.

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

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

Annotations already cover readOnly, idempotent, and non-destructive. The description adds genuinely new context: 'No new charge,' the 7-day window, retry behavior ('retries return the stored check'), the result contents, and a 'no ranking guarantee' caveat. This meaningfully exceeds what the annotations declare.

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

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

Roughly four compact clauses with no filler, and the core action is front-loaded. The telegraphic, fragmentary style (semicolon-separated clauses) is dense but each clause carries distinct information.

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

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

For a simple one-parameter tool with no output schema, the description covers the trigger condition, cost implications, timing, retry semantics, and even summarizes the return ('which JSON-LD fields are present'). Only the parameter's exact meaning and the relationship to the sibling purchase tool remain underspecified.

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

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

There is one required parameter (order_id) with 0% schema description coverage, so the description carries the burden. 'Same original key; within 7 days' hints that the id must be the original purchase key, but it never clearly ties this to order_id or states its format, leaving the parameter only partially explained.

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+resource ('live verification' of a purchased correction), which distinguishes it from the sibling kanonyr_buy_schema_repair (the purchase step). However, it never names the sibling or explicitly frames itself as the post-purchase verification step, relying on inference from 'purchased correction.'

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 triggering context ('after your authorized connector applies a purchased correction') and a hard window ('within 7 days; same original key'), which tells the agent when the call is valid. It stops short of naming the prerequisite sibling tool or stating when not to use it.

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