Convertlyft

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety bar is met. The description adds genuine context beyond that: data is 'counted from this site's own visits' and a path cannot follow one person across devices unless the site identifies them — an important limitation an agent should surface.

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 dense sentences with the core operation front-loaded and the caveat last. The parenthetical model list and platform example are somewhat redundant with schema enums but do not bloat the text excessively.

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

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

An output schema exists, annotations cover safety, and the schema fully documents all eight parameters, so the description need not explain return values or parameter details. It closes the remaining gap with the cross-device limitation; only the relationship to the sibling path tool is left unstated.

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

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

Schema coverage is 100%, so parameters are fully documented in the schema itself (goal, group, models, lookback, first_purchase all have descriptions and enums). The description mostly restates the model list and grouping concept rather than adding new meaning, so baseline 3 applies.

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

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

States a specific verb-and-resource: sales/enquiries/sign-ups shared out across prior visits by channel and platform, with six attribution models. An agent can distinguish it from most siblings, though the close sibling cvl_conversion_paths is never named or contrasted.

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

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

Usage is implied by phrases like 'any of the six models side by side, from one read' and by the stated defaults (last_non_direct, 30-day lookback, 30-day window). There is no explicit when-to-use guidance or contrast against cvl_conversion_paths, which computes paths rather than model-split credit.

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

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

Annotations already establish read-only, non-destructive, idempotent behavior, and the description adds substantial operational context beyond them: empty collections mean no one performed the action, counts disclose caps and true row counts, medians under 30 visits and form rates under 30 starts are null, and timestamps are UTC. These are exactly the behavioral details an agent needs to interpret results correctly.

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 the report's purpose and contents, and nearly every clause carries useful semantics. It is dense and somewhat run-on, especially the dead-click parenthetical, 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?

Given the rich output schema, full parameter coverage, and annotations, the description completes the picture by covering empty-list semantics, capping and pagination, statistical minimums, and time-zone handling. An agent can call and interpret this tool without needing further description-level guidance.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by explaining that counts supplies the next_cursor consumed by pages_cursor, rage_clicks_cursor, and dead_clicks_cursor, and by clarifying null-threshold and UTC semantics. It does not elaborate on limit, fields, or window_handle beyond the schema, so it is strong rather than exhaustive.

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

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

The description states a precise report resource: stuck behavior in a time window, including page attention, rage clicks, dead clicks, and form start-vs-submit. It enumerates the report's components and explicitly links row fields to cvl_dead_clicks, cvl_rage_clicks, cvl_page_attention, and cvl_form_friction, so an agent can distinguish this aggregate report from those sibling tools.

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

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

The context is clear — this is a combined struggle report for a window — but the description never explicitly says when to choose it over the separate dead-click, rage-click, page-attention, or form-friction siblings. Naming those siblings and describing interoperability implies usage without giving a selection rule or exclusion.

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

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

The annotations already establish read-only, idempotent, non-destructive behavior, but the description adds substantive context: the call behaves exactly like calling the underlying tool directly, uses the same permissions, and refuses all write or spend tools. It also frames this as a dispatcher rather than a normal read operation.

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, compact, and every sentence serves a purpose: defining the dispatch behavior, stating permission equivalence, excluding write/spend tools, and pointing to cvl_search_tools for discovery.

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 rich annotations, full schema description coverage, and an output schema, the description covers what an agent needs to know: when to use this meta-tool, where to find the target tool name and arguments, and what it will refuse. No critical behavioral gap remains.

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 the name, fields, and arguments parameters. The description says the tool is invoked by name with its arguments and routes users to cvl_search_tools, but does not add meaning beyond the schema for the fields parameter.

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

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

The description states a specific verb and resource: run a Convertlyft READ tool that is not in the direct tool list, by name and with arguments. It clearly distinguishes this meta-dispatch tool from direct tools and from write/spend tools.

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

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

It gives explicit usage conditions: use this for a read tool not in the list, use cvl_search_tools to find the name and arguments, and do not use it for write or spend tools because those are called directly. Alternatives and exclusions are both stated.

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

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

Annotations already declare destructiveHint=false... in fact destructiveHint=true and idempotentHint=true, so the description earns credit for going further: it explains the exact idempotency contract ('retry with the same idempotency_key and you get the same single marker back — never a second one') and names the undo path (cvl_change_undo). It does not describe what the marker changes or what an undo restores, so it stops short of full behavioral disclosure.

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

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

Short and front-loaded with the purpose and the precondition, but the middle sentence collapses token provenance, human confirmation, and the marked_at constraint into a garbled clause that takes a second read to parse.

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 mutation the description covers prerequisite token, human-approval workflow, retry safety, and the undo counterpart; return values are left to the output schema and the note/fields semantics to the schema. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% and every parameter is documented there, so the baseline is 3. The description implies preview_token must match the prior preview call and that marked_at is part of that preview key, but the phrasing ('and marked_at: preview, show the person') is compressed and adds little beyond what the schema fields already say.

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 ('Record that the site changed') plus its downstream purpose (measuring impact), and the adjacent tools cvl_change_preview (precondition) and cvl_change_undo (reversal), which disambiguates the trio. An agent can tell exactly what this does versus its siblings without opening a schema.

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

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

Explicit sequencing: preview first via cvl_change_preview with the same note and marked_at, show the result to the human, and apply only after they agree. The idempotency retry rule is also spelled out. This is when-to-use and when-not guidance with the alternative named.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds genuinely new behavioral facts: nothing is queued or stored by this call, and the returned token expires in 30 minutes. The token TTL is the kind of time-sensitive detail an agent cannot get from annotations or schema.

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

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

Three short sentences, each earning its place: what it shows, the no-side-effect guarantee, and the token contract. The side-effect guarantee is front-loaded immediately after the purpose.

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

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

With an output schema present, return values need not be explained, and the description covers the essential contract: non-mutating preview plus a 30-minute token. Nothing critical is missing, though it could note whether the preview reflects current state at call time or at marked_at.

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 three parameters (note, fields, marked_at) are already fully documented, including the future-date constraint. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource (preview a change marker) and explicitly ties it to the sibling cvl_change_apply, defining it as 'show exactly what cvl_change_apply would write'. An agent can distinguish this from cvl_change_apply and cvl_change_undo without opening any schema.

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

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

'without writing anything' and 'Returns the preview_token cvl_change_apply needs for this same change' make the when-to-use sequence (preview before apply) clear. It stops short of an explicit 'do not call apply without first calling this' instruction or naming when-not-to-use, so it is clear context rather than full routing guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is known. The description adds genuine context by explaining that the undo is precomputed at apply time and that a repeat call removes nothing while reporting the same result — useful detail, but it doesn't cover permission requirements or failure modes for unknown/already-consumed ids. With annotations carrying most of the load, a 3 is right.

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, each earning its place: purpose, source of the id, idempotency guarantee. Information is front-loaded with no boilerplate.

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

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

An output schema exists, so return values needn't be explained, and the idempotency note covers the main behavioral surprise. Minor gap: no mention of what happens with an unknown or already-reverted proposal_id, which matters for a destructive, idempotent tool.

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

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

Schema description coverage is 100% and the proposal_id description already says it comes from cvl_change_apply, so the description largely repeats the schema. The optional 'fields' parameter is not touched at all in the description, so no added 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 and resource — 'Remove a marker you wrote' — and ties it to the apply step by naming cvl_change_apply as the source of the proposal_id. The pairing makes the distinction from its unlock/apply siblings inferable, though the term 'marker' is never defined outright.

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?

Tells the agent the precondition (a marker previously written via cvl_change_apply) and clarifies repeat-call behavior. It stops short of an explicit exclusion such as what to do with preview-only proposals or how it differs from cvl_change_preview.

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 read-only annotations, the description adds substantial behavioral detail: deterministic checking with no model reading the sentence, exact refusal semantics, rule codes, corrected sentences, and optional site-copy mode using crawled pages. This is rich context well beyond structured 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 front-loaded with what the tool does and how to call it. It is dense and slightly repetitive around figure naming, but most sentences carry substantive guidance for a complex 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 complex checking behavior, five parameters, full schema coverage, annotations, and an output schema, the description is complete enough for an agent to invoke it correctly. It covers both receipt-backed and site-backed modes, paragraph submissions, refusal outputs, and key constraints.

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 baseline is 3, but the description adds meaningful semantics for key parameters: receipt_ids must include the evidence for the named figure, sentences naming no figure cannot be checked, and against: "site" makes receipt_ids optional. The fields parameter is not addressed in the description, preventing a 5.

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

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

The description states a specific verb and resource: submit a sentence plus evidence IDs to check it against receipts or site evidence. It clearly explains the return shape (ok, unsupported span, corrected sentence, rule_code/rule_text), so the tool’s purpose is immediately identifiable.

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

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

It gives clear usage context: submit the sentence you are about to say, submit whole paragraphs in one call, and add against: "site" for page copy. It does not name when not to use the tool or explicit alternatives, which keeps it from a 5.

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

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

Annotations already establish readOnly, idempotent and non-destructive, and the description layers on genuinely useful behavior: a hard 20-row cap, the fact that results are limited to this site's own visits, and that ordering/collapsing of repeated channels is applied. It does not cover things like cost on large date ranges or the default 30-day window, but the safety profile plus the stated data scope make this strong for a read-only tool.

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

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

It is a single front-loaded sentence that puts the resource first with zero filler or marketing language. It is dense, however, stacking multiple parentheticals ('buyers, revenue per currency, their share of all sales…', '(for recordings)') that force the reader to re-parse rather than separating what is returned from how it is scoped.

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 8 optional parameters, an output schema and full annotation coverage, the description supplies the essentials: what is counted, the top-20 limit, the data source, and the visit/output bundle. The remaining gap is routing — nothing tells an agent how this differs from cvl_attribution in outcome, which matters in a 70-tool surface with a near-identical sibling.

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 of the 8 parameters carries a substantive description, so the schema does the heavy lifting. The description reinforces output shape via the 'Meta ×2' example, which implicitly illustrates the collapse and group behavior, but it never explicitly references the group, collapse, lookback or first_purchase controls, so it adds only marginal meaning on top of the schema.

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

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

The description names the exact resource and cardinality: the top 20 source sequences buyers passed through before converting, with the concrete example 'Paid social ads · Meta ×2 > Google & other search · Google'. An agent knows precisely what report this is, but nothing in the text distinguishes it from the close sibling cvl_attribution, which a caller would plausibly confuse it with.

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

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

There is no when-to-use, when-not-to-use, or alternative-naming guidance anywhere in the description. The only hint of scope is the closing 'Counted from this site's own visits' and the passing '(for recordings)' note, neither of which tells an agent when to pick this over cvl_attribution or cvl_kpi.

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

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

With annotations already declaring destructive/openWorld/non-idempotent, the description adds substantial context an agent cannot get elsewhere: robots.txt compliance, skipping /api/auth/*, never touching private/internal addresses, no AI on pages, quota accounting (1 page per crawled page, counted at end, capped by limit), per-workspace concurrency limit of one crawl, 500-page ceiling, and that the response reports which limit was hit and when to retry. It also explains why an audit's findings never enter the workspace's to-dos/score/alerts.

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 action, the immediate return value and the duration, which is what an agent needs first. It is a dense, semicolon-heavy single paragraph carrying quotas, safety rules, limits and routing advice — all relevant, but verging on run-on and would scan better split into short blocks.

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 async lifecycle (start → status → page read), cost model against the plan quota, concurrency and page ceilings with retry behavior, webhook signing secret, and the sibling boundary for own-site crawls. Output schema exists, so return-value detail is not required, and nothing an agent needs before invoking 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 baseline is 3; the description still adds consequence-level meaning by explaining that 'links' returns only the URL map and never page text, and that 'limit' is honored as a hard cap ('never more than limit', '500 pages per crawl'). Depth, fields, render and webhook semantics remain schema-only, so it does not fully earn a 5.

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

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

States a specific verb and resource ('Start a crawl of any public website') plus what it returns immediately ('get a crawl_id straight away') and how long it runs. It also explicitly separates itself from the closest sibling: 'To audit THIS workspace's own site for the SEO tab, use cvl_run_crawl instead.'

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?

Names the follow-up tools explicitly (cvl_crawl_status then cvl_crawl_page), the alternative for own-site SEO (cvl_run_crawl), and an exclusion condition ('only on an explicit ask' for competitor audits). Mode selection guidance is also tied to a concrete outcome: links returns the URL map, full also returns page text.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world behavior, but the description adds real value beyond them: results are quoted matched sections with provenance, matching is literal word matching rather than summarization, and no account is required. The rate-limit disclosure is only a vague pointer ('same per-address limits as the other public tools').

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 compact sentences, front-loaded with the verb and corpora, each carrying distinct information (scope, return shape, matching semantics, access/limits). Minor redundancy in 'for agents' but 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 an output schema and full annotation coverage, the description only needed to explain matching semantics, provenance and access constraints, and it does. The one gap is the unexplained 'fields' projection parameter for an otherwise simple two-parameter tool.

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

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

Schema coverage is 100% and the query parameter is well illustrated in the schema, so the baseline is 3. The description adds nothing about the ambiguous 'fields' parameter, whose schema text ('top-level keys to keep, e.g. ["kpis"]') is not clarified anywhere and reads oddly for a docs search.

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?

It states a specific verb and resource ('Search Convertlyft's public documentation'), names the exact corpora (llms.txt, llms-full.txt) and the topics covered (API, MCP door, dates, limits, worked examples). It never names a sibling such as cvl_search_tools or cvl_explain, so differentiation from those tools 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?

The list of covered topics gives clear context for when this tool is the right call (looking up API details, rate limits, example flows). It offers no explicit exclusions or routing to alternatives like cvl_search_tools, so the agent must still infer the boundary.

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 real context beyond the annotations: the 'stayed fixed' clock semantics (enough page loads that the old rate would have produced at least 3 errors with none occurring), earliest-report-wins behavior, and that it records a date without touching the site. The 'reporting again changes nothing' line sits in mild tension with idempotentHint=false, but reads as describing the error's state rather than the server's side effects, so it is not a contradiction.

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 action and the deploy-gating rule, then dense qualification about the fixed-clock and refusal paths. Slightly long and colloquial in places, but nearly every sentence carries decision-relevant 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 an output schema present, return values need no explanation, and the description covers the mutation's lifecycle and failure mode. It does not mention any permission or workspace-scope requirements, which is the main remaining gap for a write tool.

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

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

Schema description coverage is 100%, so ref, fingerprint, and fields are already documented, which sets the baseline at 3. The description only indirectly touches parameters (the refusal names the error to report instead, implying ref reuse) and never clarifies the unusual 'fields' projection parameter, so it adds little over 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 (tell Convertlyft that the fix for one error is live) and immediately scopes it to a single error rather than a batch. It is clearly separable from siblings like cvl_seo_write_fix (writing the fix) and cvl_issues_list (which supplies the ref/fingerprint).

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 timing rule — call only once the change is deployed, not when written or merged — plus an exclusion: errors that are set aside or merged are refused and the refusal names the error to report instead. There is no ambiguity about when this is the right call.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely non-obvious behavior: no figure value is returned, the handle carries the window but not the filters, and counts are undercounted before the attribution epoch. That is real added 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?

Front-loaded with the resource and scope, but the opening sentence is a long comma-chained enumeration and the second paragraph is dense with multiple interleaved instructions. Every sentence carries information, yet the structure could be broken up so the cvl_kpi routing stands out instead of being buried mid-paragraph.

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?

Output schema exists, so return values needn't be described, and the description still flags that no figure value comes back. Combined with the handle/filter caveat and epoch undercounting note, an agent has everything needed to call it correctly against the sibling tools.

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

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

Schema coverage is 100%, so per the baseline this lands at 3 even though the description adds the important handle-scope caveat. It reinforces that source/campaign must be repeated and that verbose supplies constant prose, but these are restatements of the schema's own parameter descriptions rather than new semantics.

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 — explains the methodology behind one KPI header figure — and explicitly enumerates what the explanation contains (definition, population/denominator/numerator, filters, withholding condition, attribution epoch). It separates itself from cvl_kpi in the same breath by declaring it returns no figure value.

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

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

Explicit when-to-use and routing: call cvl_kpi for the value, call this for the methodology, and pass the same window_handle. It also gives the operational instruction to repeat any source or campaign, with the consequence spelled out (otherwise you get the unfiltered population).

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 safe, idempotent read; the description goes well beyond that by disclosing the response contract (figure objects with state/value/display/previous/delta, and no value key when state is non-ok), the crucial interpretation rule that a non-ok figure means "unknown", never zero, and the counting conventions (visits attributed to their start day, crash-free rate counting visits with unhandled errors).

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

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

It is front-loaded with the metric list, which is good, but the whole thing is one dense run-on block with no visual structure, and the trailing "home:" fragment introduces a figure set without saying how an agent requests it — the schema has no view-selector parameter. That dangling reference costs real clarity.

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

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

For a read-only tool with a full output schema, this covers nearly everything an agent needs: interpretation of state, error remediation, and window chaining. The unresolved gaps are how the "home" figure set is selected and what `fields` pruning does to the envelope.

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 earns a bump by explaining the multi-call idiom — reuse window.handle so the whole chain reads one window — and by noting that source/campaign filtering is what can push a window into window_too_large. It says nothing extra about `fields` or the campaign parameter.

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

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

The description enumerates the exact resource returned (visitors, visits, conversion rate, revenue by currency, engaged time, site health) and ties it to the dashboard header, which is far more specific than the title alone. It never references a sibling tool, so an agent gets no explicit routing help, but the metric set is distinctive enough that confusion is unlikely.

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

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

It gives real operational guidance: read "state" first, pass from/to once and reuse window.handle on later calls, and what to do when window_too_large is returned (drop the filter or shorten the range). What it lacks is any statement of when to prefer this over adjacent reporting tools such as cvl_behavior_report or cvl_attribution.

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 contains rich behavioral detail — asynchronous worker execution, return of run id/status rather than a report, cap refusal naming cap and spend. However, it says asking twice on one day attaches to the existing row rather than starting a second run, which contradicts the annotation idempotentHint=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 dense sentences with no wasted text. The key distinction that this queues rather than executes is front-loaded, and the cap and duplicate behavior follow logically.

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, the description need not explain return values, and it correctly notes that the call returns a run id and status rather than a report. It is mostly complete for an async queue tool, though the idempotency contradiction leaves the agent with conflicting guidance.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description adds no parameter-specific meaning beyond the schema, 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 gives a specific verb and resource: 'Queue today’s operator run for this workspace.' It is clear what the tool does, though it does not explicitly distinguish this 'operator run' from sibling run-related tools such as cvl_seo_run_flow or cvl_run_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?

It explains when calls are refused due to the daily cap and what happens on repeat requests, which is useful operational context. It does not explicitly name alternative tools or say when another sibling should be used 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 (readOnly=false, destructive=true, openWorld=false), the description discloses the crucial non-obvious trait: nothing is applied, no credential can approve, including the agent's own. It also explains why baseline and revert_plan are mandatory (staleness-checkability and undo-ability) and that re-proposing a fix_identity supersedes rather than duplicates the card — real behavioral information not derivable from the flags.

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

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

Four sentences, front-loaded with the core action and the non-application constraint; each later sentence carries a distinct rule (no self-approval, required evidence, supersede behavior). Slightly dense but 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 annotations, full schema coverage, and an output schema already present, the description covers the main risks an agent needs: it cannot self-approve and it must supply baseline and revert_plan. Minor omission is the confusing fields parameter semantics and what the returned card contains, which the output schema presumably supplies.

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 six parameters, setting the baseline at 3. The description adds rationale for baseline and revert_plan (a proposal an owner cannot staleness-check or undo should not be accepted), but says nothing extra about title, detail, or the envelope-key semantics of fields.

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

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

The first sentence gives a specific verb and object: queue a fix for the owner to approve, and the second sentence pins down the boundary (it does not and cannot apply changes). An agent can separate this from an apply-style sibling by behavior, though no sibling is named explicitly.

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

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

Usage is implied rather than stated: you call this when a fix needs human sign-off, and approval is a human act with no credential path. However, it never names the alternative tools (e.g. cvl_change_preview, cvl_change_apply, cvl_change_undo) or tells the agent when to skip proposing in favor of those, so routing still requires inference from sibling names.

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

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

Goes well beyond the annotations: discloses a ~45s wait, no-account access, per-address limits (20/min, 200/day, 10k/day global) with HTTP 429 and Retry-After semantics, and a 5-new-scans/day quota where reused scans don't count, plus an error carrying retry_after_seconds. This also explains why the tool is flagged non-read-only/destructive: supplying a url starts or reuses a scan.

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-loads what the scan returns before the operational detail, and every clause is informative. The rate-limit/quota passage is dense and runs long, but it is the kind of detail an agent needs before calling a metered endpoint.

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?

Despite having an output schema, it summarizes the payload shape, and it covers latency, auth requirements, quota, error signaling, and the relationship to the sibling scan tool. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema lacks: a url 'starts or reuses that scan' and reusing does not consume the scan quota, which changes how an agent should choose between url and scan_id. The `fields` parameter is not addressed at all in the description.

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

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

States a specific resource and verb: what a scan found about AI agents on a public site, enumerating the concrete outputs (agent-readiness level L0-L4, per-crawler robots.txt access and what the request got, llms.txt presence, report_url). It explicitly distinguishes itself from cvl_public_seo_scan by saying it reads the same crawl rather than performing a second one.

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

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

Gives clear routing: pass the scan_id you already have, or a url which starts or reuses that scan, and points to cvl_public_seo_scan as the producer of scan_id. It does not say when to prefer the sibling SEO scan instead, so the alternative direction is only one-way.

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

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

Goes well beyond the annotations: it discloses the 45-second ceiling, the {status: "running", scan_id} fallback, 24-hour readability and reuse of scan_ids, 30-day deletion, per-address rate limits (20/min, 200/day) and the 10,000/day global cap, the 5-new-scans/day quota, and the HTTP 429 / retry_after_seconds error contract. It also explains the 'destructive' cost implied by the annotation: quota consumption, not site mutation ('nothing changed on the site').

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

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

Front-loaded with purpose, then returns, then fallback, then limits — a sensible order. The prose is dense and the limits sentence runs long with nested parentheticals, but every clause carries operative 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?

An output schema exists, yet the description still sketches the return shape (score/100 with four parts, issue counts, top 3 issues, first fix, checks not performed, report_url), and it covers the async fallback, quota, retention, and error paths. Nothing an agent needs to call it and handle the response 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 both url and fields are already documented with examples. The description adds only the home-page starting point implicitly and never explains 'fields' (envelope keys vs metric names), so it does not meaningfully exceed the schema 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 first clause names a specific verb and resource ('Scan a public website for SEO problems') and scopes it with concrete constraints: up to 16 pages, robots.txt obeyed, no JavaScript. It is clearly separable from siblings like cvl_seo_audit or cvl_public_agent_readiness, and it explicitly hands off to cvl_public_seo_scan_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 states the no-account path, the 45-second wait behaviour, and the exact condition and tool to use when the scan is still running ('call cvl_public_seo_scan_result with that scan_id'). What it lacks is an explicit statement of when NOT to use this versus cvl_seo_audit (the signed-in, deeper audit).

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

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

Annotations already cover read-only/idempotent safety, but the description adds material behavior beyond them: a ~45s wait, the running-status fallback shape {status: "running", scan_id}, and quota neutrality. It also discloses retention: readable at least 24 hours, 24-hour reuse of finished scans, deletion after 30 days.

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

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

Dense and front-loaded: identity and behavior first, then the negative constraint, then retention. Every clause carries information, though the parenthetical retention sentence is slightly packed and could be split.

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?

Output schema exists, so return shape need not be explained, yet the description still flags the async-running case. Timeout, quota, and retention are all covered, leaving no operational gap for a two-parameter read tool.

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

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

Schema coverage is 100%, so both parameters are documented in the schema itself. The description corroborates that scan_id comes from cvl_public_seo_scan, but says nothing about the optional fields filter. Baseline 3 is appropriate when the schema carries the parameter burden.

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: retrieves the result of a scan started by cvl_public_seo_scan, keyed by scan_id. It explicitly names the sibling that starts the scan, so an agent can distinguish the two without reading schemas.

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

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

Clear when-to-use (after cvl_public_seo_scan returns a scan_id) and when-not (does not start a scan, does not count against the 5-per-day quota). The alternative path is named explicitly, leaving nothing to infer.

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 key behavior: append-only ('You cannot delete anything here; only the owner can, from their settings') and a hard validation rule that unsupported findings are rejected by design. Annotations already flag the write/mutation profile, so the description's remaining contribution is the retention/refusal semantics. There is mild tension with destructiveHint=true (it stresses nothing is deleted), but this reads as clarification rather than a contradiction. Idempotency and rate/pagination behavior are unmentioned.

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

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

Three short sentences, front-loaded with the purpose, then the evidence rule, then the immutability caveat. No filler, though the evidence requirement is partly restated from the schema and could be tightened.

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

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

For an 8-parameter write tool with 100% schema coverage and an output schema, the description covers the non-obvious requirements (conditional evidence, append-only) without needing to describe return values. Adequate for correct invocation; parameter aliasing is the only notable omission.

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 baseline is 3, but the description adds real cross-parameter logic the schema does not express: which kinds force receipt_id and the window, and which kinds are exempt. It does not touch the 'from/to' vs 'window_from/window_to' aliasing or the 'fields' envelope-key semantics, which is the only 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 opening sentence gives a concrete verb and resource — appending one row to the workspace ledger — plus the payoff ('so the next conversation does not derive it again'). That is far more specific than the title alone and implicitly separates memory-writing from the many read/analysis siblings, though it never names an alternative tool such as cvl_todo_add or cvl_check_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?

It clearly sets conditions per kind: a 'finding' MUST carry receipt_id and a window or it is refused, while decisions, preferences and questions need no evidence. That is usable when-to-use style guidance tied to the kind parameter. It stops short of saying when to prefer this over sibling memory/todo 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?

Annotations flag destructiveHint=true and idempotentHint=false, and the description goes well beyond them: it states the default is non-mutating, describes the preview payload (how many pages affected, what each reverts to, up to 10 examples), the alternate-rule fallback behavior, undo semantics, and the blast radius ("changes how pages are grouped in reports; it changes nothing on the site"). This is exactly the context annotations cannot carry.

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

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

Front-loaded with the action and the id source, and every clause carries information (preview default, payload shape, approval gate, undo, impact scope). It is dense and slightly run-on with em-dash chains, but nothing is redundant.

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

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

Although an output schema exists, the description still characterizes what a preview returns and what changes on apply, plus the undo path — everything an agent needs to call this destructive tool safely. No material gap remains.

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

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

Schema coverage is 100%, so the schema carries the parameter contract and a 3 would be the floor. The description adds real meaning for id (sourced from cvl_page_type_rules) and frames dry_run as a preview/apply switch with an approval condition; the opaque 'fields' parameter is left to the schema.

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

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

Specific verb+resource ("Remove one of the owner's page type rules") with an explicit key source ("its id from cvl_page_type_rules"), which distinguishes it from cvl_set_page_type and the other setter siblings. An agent knows exactly what object is deleted and where the identifier comes from.

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 default ("A PREVIEW unless the call says dry_run:false"), an explicit gate ("Show the owner and apply only on their yes in the chat, with dry_run:false"), and names the recovery path (the undo call restores the rule and its pages). When-to-use and when-not are both 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?

Adds substantial context beyond the annotations: it consumes plan quota ('counts toward the plan's Pages scanned'), starts immediately, runs a few minutes, and dry_run checks nothing. The destructiveHint=true annotation is not explained, though – an agent isn't told whether a new crawl replaces or invalidates previous crawl data, which is the main behavioral risk here.

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

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

Dense but front-loaded: cost model, scope, duration and follow-up tools all appear in a single efficient paragraph with no filler. Minor awkwardness in the parenthetical dry_run clause and the 'cvl_site_pages / cvl_page_content' shorthand, but nothing wasteful.

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

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

Given an output schema and annotations, the description covers cost, duration, live progress and next-step tools well. The remaining gaps – the destructive replacement semantics and the cvl_crawl_start distinction – are the ones an agent most needs before invoking a mutation tool.

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

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

Schema description coverage is 100%, so all four parameters are already documented. The description reinforces max_pages ('at most max_pages') and dry_run ('says how many pages are left and checks nothing') inside the narrative, but adds no syntax or format detail and never touches 'fields' or 'confirm_cost'. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Start a crawl of this workspace's own site') and enumerates what it collects (status, title, description, headings, words, technical issues). It distinguishes itself from paid external providers ('A first-party crawler, not a paid provider') but never mentions the sibling cvl_crawl_start, leaving genuine ambiguity about which crawl tool to pick.

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

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

Explicit trigger conditions: 'Use it when the person asks for a crawl or an audit, or when they ask about their pages and no crawl exists yet.' Also clarifies downstream usage (cvl_site_pages / cvl_page_content after completion) and that the SEO tab follows it live. It stops short of naming when to prefer cvl_crawl_start or cvl_public_seo_scan instead.

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

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

Annotations already declare read-only, idempotent and closed-world, so the safety profile is covered. The description adds what the annotations cannot: the result shape by default (name, title, one line per tool) and that schema:true expands to full input schemas, plus the boundary that this catalogue only surfaces non-write tools. Return detail is partly redundant with the presence of an output schema, which keeps it from a 5.

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

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

Four short sentences, front-loaded with the core purpose and followed by scope, output shape and routing. Nearly every clause earns its place; 'Your list holds a core set; behaviour, SEO, errors, site and workspace reads are here' is slightly compressed to the point of being cryptic about the coverage boundary.

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 discovery tool with an output schema, this covers purpose, routing to cvl_call_read, the write-tool exclusion and result verbosity. Only minor gaps remain: the 'fields' envelope parameter and the limit cap are left entirely to the schema, and the categories named ('behaviour, SEO, errors, site and workspace reads') are not mapped to anything actionable.

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 query, limit, fields and schema are already fully documented in the schema. The description only restates one of them (schema:true adds the input schema) and says nothing about query phrasing, the limit cap or what 'fields' envelopes mean — baseline 3 is correct when the schema carries the 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?

States a specific verb and resource ('Find a Convertlyft tool') plus the scope: tools not already in the agent's list, and matching skills. It also carves out the adjacent siblings explicitly — 'Run a read it finds with cvl_call_read' and 'Writes are always in your list already' — so an agent can distinguish this catalogue-search tool from cvl_call_read, cvl_skills_list and cvl_docs_search without opening any schema.

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

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

Gives an explicit trigger (the tool you need is not in your list), names the follow-up tool for the discovered read (cvl_call_read), and rules out a whole class of alternatives (writes) with a reason. This is when-to-use plus when-not-to-use plus alternatives in three sentences.

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 idempotentHint=true, so the trailing 'Idempotent.' adds no new information. The description says nothing about what happens to keywords already on the list, whether there is a quota, or how market/location resolution behaves. It does not contradict the annotations, but it adds almost nothing beyond 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?

Two short sentences with the action front-loaded and no filler. The brevity is close to under-specification, but nothing written 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?

An output schema and rich annotations reduce the burden, but for a mutation tool whose name overlaps confusingly with cvl_seo_track_keywords, the description should have stated the relationship between 'adding to the keyword list' and 'tracking'. That gap leaves an agent guessing between two plausible siblings.

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

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

Schema description coverage is 100%, so all six parameters (including market/location_code and page_url/pageUrl aliases) are documented in the schema itself. The description only hints that the page parameter is optional; it adds no syntax, limits, or alias guidance beyond the schema. Baseline 3 applies.

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

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

'Add searches to the keyword list, optionally for one page' gives a verb and a resource, so the basic action is understandable. But the title says 'Add searches' while the name says 'keywords', and the description never distinguishes this from the sibling cvl_seo_track_keywords (or cvl_seo_untrack_keywords), which an agent would naturally consider for the same task.

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

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

No statement of when to use this instead of cvl_seo_track_keywords, cvl_seo_untrack_keywords, or cvl_seo_map_keyword_page. The only hint is 'optionally for one page', which alludes to scoping but does not say when page scoping 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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=true) by explaining exactly what mutation occurs: the new market copies the primary market's tracked searches, is checked weekly on Mondays at 02:00 UTC, counts toward keywords tracked, and does not change the primary market. It also explains the dry_run side-effect profile and the duplicate rejection, none of which the annotations 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?

Dense but front-loaded: the core action and its three dimensions come first, followed by scheduled behavior, cost implications, and the dry_run clause. The semicolon-chained sentences pack a lot but every clause (weekly cadence, quota, primary unchanged, nothing bought) carries decision-relevant 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 5-parameter mutation with an output schema, this covers what an agent needs: prerequisites (market not already tracked), effects (copied searches, weekly checks, quota impact), preview mode, and cost ('nothing is bought'). Return values are handled by the output schema, so nothing material is missing.

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

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

Schema description coverage is already high (80%), so the baseline is 3, and the description adds real meaning for dry_run ('answers what would be added and when the first check runs, without adding anything') and clarifies that the market dimension is country/language/device. The 'fields' parameter is only documented in the schema, not the description, so it is not a full 5.

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

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

States a specific verb and resource ('Start tracking this site in another market') and immediately defines the market as the (country, language, device) triple. That is enough to separate it from siblings such as cvl_seo_add_keywords or cvl_seo_track_keywords, which operate on keywords rather than markets.

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 conditions and exclusions: an already-tracked market is refused, the primary market is unaffected, and dry_run is for previewing what would be added and the first check date. It stops short of naming an alternative tool or saying when not to add a market at all, so it falls just below the explicit-alternatives bar.

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

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

Annotations already flag this as a non-read-only, destructive, non-idempotent purchase, and the description adds real behavioral detail beyond that: quota is drawn from the site's daily paid-search limit, there is no per-call confirmation, answers are cached so repeats are instant, refresh re-buys, and dry_run reports rounded usage plus fits_today. Minor redundancy ('Included in the plan, inside this site's daily limit' appears twice) keeps it from a 5. No contradiction with 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 purpose is front-loaded, but the text repeats the plan/quota message twice and the opening clause is fragmentary ('Whether AI assistants name a site: answers from...'). Several sentences earn their place (refresh, dry_run, caching), but the duplication costs it.

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 six parameters, a purchase-cost model, and an output schema that covers return values, the description supplies what an agent needs to call it correctly: sample nature, caching, quota consumption, and dry-run preview. The main gap is sibling differentiation against other site-research tools in this namespace.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further on two key params: refresh is explained as 'buys again' versus reading the stored answer, and dry_run is explained as returning rounded quota usage and fits_today without purchasing. limit, fields, and confirm_cost are left to the schema, which already documents them.

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: AI-assistant answers from a tracked prompt panel that name a site, with the fields returned (platform, question, mention flag, excerpt). It also clarifies the scope caveat ('a sample of tracked answers, not every answer'), so an agent knows what it gets. It never names a sibling tool to contrast with (e.g., cvl_seo_serp or cvl_public_seo_scan), so it stops short of a 5.

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

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

Gives concrete usage conditions: dry_run:true to preview quota without buying, refresh:true only when you want to pay again, and cvl_usage to see what was consumed. There are no explicit exclusions or 'when not to use this vs alternative site-research tools', so it is clear context without full routing guidance.

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

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

Annotations already cover read-only, idempotent, non-destructive. The description adds real behavior beyond them: freshness rules (a re-check, a 0-page run, or a running crawl never replaces the stored full crawl; full_run names it), that a re-check clears findings it no longer sees, and that page rows may live on the crawler rather than in the payload. That is meaningful state semantics an agent could not infer.

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 whole definition is a single sprawling sentence riddled with parentheticals and em-dashes; the core purpose is buried behind clauses like 'a newer list re-check ... never replaces it'. The information is dense with little filler, but it is not front-loaded and forces the reader to parse before acting.

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

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

An output schema exists, yet the description still explains all three modes (summary, single-issue detail, paged rows) and the freshness caveat, which is what an agent needs for a multi-mode read tool. Minor gaps remain, e.g. how to page through the issue list itself and whether `fields` filters issue-detail responses.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema, which sets the baseline at 3. The description does add the multi-mode framing (issue returns fix text and sample pages; limit/cursor stream page rows), but that largely restates what the schema fields say, and it never clarifies how `fields` interacts with the issue-detail or paging modes.

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

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

The description names a concrete resource and scope: the latest full crawl of the site, with run status, issue lanes, top landing pages, crawl-over-crawl changes and past runs. It also distinguishes itself from cvl_site_pages for crawls whose rows stay on the crawler. The verb is only implied ('the latest full crawl ... as a summary') and the syntax is convoluted, so it is clear but not immediately scannable.

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?

One alternative is routed explicitly: 'a crawl whose rows stay on the crawler (run.rows_on_crawler) is read with cvl_site_pages.' Beyond that edge case there is no when-to-use guidance relative to nearby siblings such as cvl_run_crawl, cvl_crawl_start, cvl_public_seo_scan or cvl_site_pages in the normal case. Usage is implied by what the tool returns 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 alone only flag destructiveHint/idempotentHint=false; the description goes well beyond them by disclosing the billing model (quota spend rather than per-call charge, hence 'destructive'), result caching ('stored, so asking the same question again is instant'), refresh semantics, the dry_run preview mode, and that confirm_cost causes refusal rather than a charge. That is exactly the kind of hidden cost/caching/auth context annotations cannot convey, with no contradiction of the flags.

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

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

It is front-loaded with the substantive result content, but the clause 'Included in the plan, inside this site's daily limit' appears twice in near-identical form and the description sprawls across billing, caching, and preview concerns in a somewhat stream-of-consciousness flow. Slight tightening would make it clearly efficient.

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

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

With an output schema present, return values need not be explained, and the description covers cost, caching and preview sufficiently for an agent to call it safely. The remaining hole is sibling disambiguation against cvl_seo_backlinks, which leaves the definition just short of fully self-sufficient.

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

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

Schema description coverage is 100%, so all five parameters are documented structurally and the baseline is 3. The description restates refresh and dry_run behavior almost verbatim from the schema and adds only marginal framing (quota usage, fits_today) — useful connective context but not much 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?

The description names a concrete verb+resource — headline backlink counts (referring domains, backlinks, broken backlinks, referring pages, first-seen) for any site — so an agent knows exactly what it returns. However, there is a near-duplicate sibling cvl_seo_backlinks and the description never distinguishes this profile/headline tool from it, leaving the agent to guess between two very similar options.

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 explains the cost/limit context well ('included in the plan, inside this site's daily limit, no per-call confirmation') and when to use dry_run and refresh, which is real guidance. But it gives no direction on when to choose this over cvl_seo_backlinks or cvl_seo_domain_overview, which is the most consequential selection decision here.

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 significant behavioral traits: spam-filtered domains over a score of 30 and unranked domains with no spam score are hidden but counted in linkGapsHidden, and results are 'served from stored pulls' rather than live data. This meaningfully informs interpretation of the output, though it does not cover other operational details such as snapshot cadence or access prerequisites.

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 the core purpose and consists of three information-bearing sentences. The phrasing is occasionally jargon-heavy ('the SEO room shows it'), but there is little wasted text.

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

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

With an output schema and full schema coverage for the only parameter, the description needn't explain returns or parameter syntax. However, in a crowded SEO toolset it omits the crucial context of how this tool differs from cvl_seo_link_gap, cvl_seo_backlink_profile, and cvl_seo_referring_domains, leaving selection ambiguity.

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% for the single optional 'fields' parameter, so the schema already explains its purpose. The description adds no additional parameter meaning, which is acceptable given the high coverage but not enriching.

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 resource (domains and pages linking to the site) and the two data views returned: snapshot-level backlink counts and a newest link-gap read against rivals. It does not, however, distinguish this tool from closely related siblings such as cvl_seo_link_gap, cvl_seo_backlink_profile, or cvl_seo_referring_domains.

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

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

There is no explicit guidance on when to use this tool versus alternatives. The description only characterizes the data returned; an agent must infer usage from the phrase 'newest link-gap read' despite separate sibling tools dedicated to link gaps and backlink profiles.

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

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

Annotations already declare this as destructive, idempotent, and not read-only; the description mostly repeats the idempotent hint and adds that multiple items can be processed in one call. It does not explain the consequences of "clear" or what gets removed beyond the annotation-level warning.

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 two tight sentences with the operation front-loaded and no wasted text. It states the main action, the batch capability, how to identify the brief, and the idempotency note efficiently.

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 annotations and output schema, the description provides enough context to select and invoke the tool. However, it references cvl_seo_brief, which is not present in the sibling list, and does not clarify how it differs from cvl_seo_add_keywords.

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 high at 83%, so the schema already defines most parameters. The description adds domain context for search and keywords, but it calls the "none" decision "clear," which does not exactly match the enum value and could cause minor confusion.

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

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

The description uses a specific verb and resource: deciding searches under a stored SEO content brief's "Keywords to add" with add, skip, or clear actions. It clearly describes the operation but does not distinguish it from the similarly named sibling cvl_seo_add_keywords.

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 specifies the context of use: keywords listed under a stored brief's "Keywords to add," and notes that several can be handled at once. It does not provide explicit when-not guidance or contrast with the sibling add-keywords tool.

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

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

Adds substantial context beyond the annotations: it creates a draft first if none exists, refuses with a reason when a brief cannot become a draft, the next crawl ticks checklist items, and the brief is Confirmed live only when title and H1 match. What it does not disclose is the consequence of destructiveHint=true — that a page goes publicly live and whether that can be undone.

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

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

Purpose and address rules are front-loaded and every clause carries real information about publish, read-back, and confirmation. The long parenthetical sentence about views/position/clicks is genuinely hard to parse, which costs a point.

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

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

For a non-idempotent, destructive, multi-step tool with an output schema, the description covers the full lifecycle — publish, draft fallback, refusal, crawl read-back, Confirmed live criteria, downstream reporting, and cost. The only gap, undo/reversibility, is minor given the annotations flag destructiveness.

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

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

Schema description coverage is 100%, so both the url default and the market/location_code alias are already documented in the schema. The description restates the url default but says nothing about 'fields' or 'keyword', so it adds little beyond structured data; baseline 3 applies.

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

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

States a specific verb and resource — mark a content brief's page as live and publish its draft — and distinguishes itself from cvl_seo_draft_publish by framing that tool's publish step as a sub-behaviour of this one. An agent can tell what this 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?

Gives clear context: use it once the page is actually live, omit url to fall back to the brief's page, and re-saying with a new address restarts the read-back. It implies but never explicitly states the exclusion ("if you only want to publish and not mark live, use cvl_seo_draft_publish"), so routing is inferred rather than 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?

The description discloses important behavior beyond the annotations: it is free once per search per day, repeated checks today are skipped, the response says so, the call starts immediately without waiting, and positions appear on cvl_seo_rank within minutes. It does not explain why the annotations mark this destructive, but the non-idempotent daily quota behavior is clearly surfaced.

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

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

The definition is front-loaded with the core action and scope, then adds only operationally important constraints: daily quota, async timing, tracked-search requirement, and market default. The sentences are dense but each carries relevant 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?

Given the annotations, full parameter schema, and output schema, the description covers what an agent needs: scope, quota behavior, async result timing, tracked-search prerequisite, and market default. Nothing essential 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 all five parameters are already documented in the schema. The description adds useful meaning for keyword and market omission, but device and fields rely entirely on the schema, so this is the baseline score when the schema carries the detailed semantics.

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: checking current top-10 rankings for one tracked search or all searches in a market. It distinguishes the tool from nearby siblings by naming cvl_seo_rank as where results land and cvl_seo_track_keywords as how tracked searches are added.

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

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

It gives clear usage conditions: use keyword for one search, omit keyword to check every tracked search, omit market for the primary market, and only tracked searches can be checked. It also names cvl_seo_track_keywords as the way to add a search, though it does not explicitly compare itself to alternatives such as cvl_seo_ranked_keywords or cvl_seo_serp.

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 behavior beyond the annotations: it discloses that answers are stored and re-asking is instant, that refresh:true buys a fresh answer at cost, that dry_run reports rounded limit usage and fits_today without buying, and that no per-call confirmation is charged. This makes the destructiveHint=true (budget-consuming) consequence concrete and actionable.

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-loads the core result and ordering, which is good, but 'Included in the plan, inside this site's daily limit' is stated twice in near-identical form, and the dry_run sentence restates what the dry_run schema entry already says. Tightening would let the same content land in fewer sentences.

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

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

With an output schema present, return values need not be spelled out, yet the description still names the key columns (volume, competitor ranking page). Cost, caching, and dry-run behavior are all covered for a 9-parameter, budget-consuming tool. Minor gaps remain around the fields/envelope projection and limit interplay, though the schema covers those.

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 domain, competitor, limit, refresh, dry_run, fields, confirm_cost, language_code and location_code. The description reinforces the cost/semantics of refresh and dry_run but adds no syntax or defaults (e.g. limit default 50, location fallback) beyond what the schema states. Baseline 3 applies.

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

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

States a specific verb and resource: the searches a competitor ranks for that the domain does not, ordered by best competitor position, with monthly volume and the competitor's ranking page. An agent can tell this is a keyword gap tool rather than a link gap or ranked-keyword listing. It never names a sibling explicitly (e.g. cvl_seo_link_gap, cvl_seo_ranked_keywords), so it falls short of a 5.

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

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

Clear operational context: research is included in the plan, bounded by the site's daily paid-search limit, and requires no per-call confirmation. It also directs the agent to cvl_usage for consumption and explains refresh vs. cached reads. No explicit exclusions or 'use X instead' routing to sibling gap/ranked-keyword 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?

It discloses traits that the annotations only hint at: each call consumes paid search data against this site's daily limit, there is no per-call confirmation, answers are cached and reused unless refresh is set, and dry_run returns rounded usage plus fits_today. It doesn't contradict the destructive/openWorld hints, and it clearly signals a metered, billable action.

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 leads with the core purpose, which is good. However, it repeats the plan/daily-limit point twice ('included in the plan, inside this site's daily limit' and 'Included in the plan, inside this site's daily limit'), and it crams cost, caching, usage, and dry_run into one dense paragraph, so the information isn't fully front-loaded.

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

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

It covers behavior, cost, and the dry_run/refresh interplay, and an output schema exists, so return fields needn't be described. It doesn't explain the default market that location_code omits or the semantics of fields, which would have closed the remaining gaps for a 7-parameter tool.

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

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

Schema coverage is 100%, with domain, fields, dry_run, refresh, confirm_cost, language_code, and location_code each documented in the schema. The description restates refresh/dry_run/caching, which adds little information beyond the schema, so it stays at the 3 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?

It states a specific resource (a domain's organic footprint in one country) and enumerates the metrics returned: number of ranking searches, top-3 count, and monthly traffic estimate. It doesn't name a sibling tool like cvl_seo_ranked_keywords or cvl_seo_keyword_metrics, so the agent must infer which one fits, which keeps it below 5.

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

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

It explains context well: research draws on plan allowance and a daily limit, dry_run checks whether a call fits, refresh repurchases a stored answer, and cvl_usage reports consumption. It doesn't explicitly exclude cases or point to alternatives such as cvl_seo_keyword_metrics for per-keyword data, so sibling routing is left implicit.

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

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

Goes well past the annotations: the call is asynchronous (returns brief_id, status, poll_after_s immediately), billing is counted once when the brief reaches Ready with rebuilds free, briefs under 7 days are reused, and it discloses the draft_not_saved failure and the [Fill in: …] gap marker for unsupported claims. It also makes clear it saves a draft rather than publishing, which is the key distinction behind 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?

Purpose and async behavior are front-loaded, but the body is one dense paragraph of stacked parentheticals ('one of the month's, counted once it is Ready; a rebuild… is free') that is harder to parse than it needs to be. The information earns its place; the packaging does not.

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