XeoRank

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent write with open-world access. The description adds real behavioral detail beyond that: it replaces a specific marker, and it clears the score so a re-score is required afterward — a side effect an agent would otherwise miss.

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 mutation itself, then the precondition, then the side effect. Every sentence carries distinct information with no padding.

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

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

For a no-output-schema mutation tool, the description covers the write target, the marker replacement, the precondition and the score-clearing side effect. The main residual gap is the return value/confirmation format, which is minor given the tool's simplicity.

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

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

Schema description coverage is 100%, so url, title, brief_id and claim_id are all documented. The description's note that claim_id comes from suggest_sources largely repeats the schema's own wording, adding little new meaning. 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: writes the user-chosen source into the draft at the claim as a markdown link, replacing the [SOURCE NEEDED] marker. This is concrete enough to separate it from sibling tools like suggest_sources or assist_draft.

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?

'Only call after the user picked it' gives an explicit precondition, and pointing to suggest_sources identifies where claim_id originates, implicitly routing the agent through that tool first. It does not state what to do if the user changed their mind or if the marker is absent, but the core when-to-use guidance is clear.

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

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

With annotations already declaring destructiveHint=true and idempotentHint=false, the description adds real behavioral context: automatic dedup, a 1-200 batch bound, mixed-list tolerance, and that adding does not trigger the paid rank check while intent/funnel_stage are persisted. It does not explain whether existing tracked keywords are overwritten, but the added operational detail goes meaningfully 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 core purpose, then format, examples, and follow-up tools in a logical order. The two worked examples earn their space, though the run-on parentheticals make it denser than strictly necessary.

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

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

For a two-parameter mutation tool with no output schema but full annotation coverage, the description supplies enough to call it correctly: accepted formats, field enums, limits, and follow-up tools. Only the effect on pre-existing tracked keywords is left unaddressed.

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% (baseline 3), yet the description still adds substantial meaning the schema omits: it enumerates allowed intent values (informational/commercial/transactional/navigational), funnel_stage values (tofu/mofu/bofu), the extra optional fields (cluster_name, notes, source), the accepted string-vs-object formats, and the 1-200 count limit.

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 ('Save target keywords to a brand's account') and immediately clarifies the scope as the keywords the user decided to track. It names sibling tools (list_tracked_keywords, get_keyword_funnel) so an agent can distinguish saving from recalling and reviewing.

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 for use ('the keywords you and the user decided to track and build for') and routes follow-up work to list_tracked_keywords and get_keyword_funnel. It stops short of naming true alternatives like remove_tracked_keywords, promote_research_keywords, or seed_keywords_from_gsc, so it is strong but not complete on when-not/alternatives.

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 the safety profile (mutation, idempotent, non-destructive, open-world), so the description's job is lower. It adds genuinely useful behavior: the redirect is re-verified live before any change, and two refusal conditions are spelled out. It stops short of describing what happens to existing crawl data or the response shape, hence not a 5.

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

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

Three tight sentences, front-loaded with the action, then the trigger condition, then the refusal guard. No sentence is filler and the ordering matches how an agent decides and calls.

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

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

For a one-parameter mutation tool with no output schema and rich annotations, the description covers the action, the trigger, verification, and failure modes. The only minor gap is that it doesn't indicate the return/outcome shape or the effect on prior crawl results.

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

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

There is a single parameter with 100% schema description coverage, so the schema already carries the semantics. The description reinforces the meaning ('the site whose homepage redirects elsewhere') but adds no syntax or format detail beyond the schema, making the baseline 3 correct.

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: point the site at the domain its homepage redirects to and re-crawl. It is clearly distinguishable from siblings like refresh_site or start_crawl because it names the exact precondition (homepage 301s off-site) that only this tool addresses.

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

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

It gives an explicit, observable trigger: use when a crawl returns 0 pages and coverage carries `seed_redirects_to` with a 'X redirects to Y' status detail. It also states when the tool will refuse (target already a site, redirect gone), so the agent knows both when to call it and when it will fail.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context by disclosing the return payload (base URL, auth, per-tool endpoints), which annotations cannot 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?

Two tight sentences with the purpose front-loaded and the return contents second. Minor looseness in 'straight from the REST API with your own key' but no filler or redundancy.

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

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

With no input schema and no output schema, the description carries the burden and does explain the returned fields. It could say more about format or how endpoints map to tools, but it's sufficient for an agent to know what to expect.

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

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

The tool takes zero parameters, so there is no parameter semantics to describe; baseline 4 applies. Nothing is missing here.

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 purpose: a meta-tool that returns the REST API base URL, auth, and endpoints behind heavy tools so data can be fetched directly. It's distinct from every sibling (all of which are SEO/WP operations), so an agent can identify it quickly.

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

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

Provides a clear when-to-use rationale: 'instead of pulling it through this context,' i.e., use this when you want to process data in code with your own key. It names the alternative pattern (context/tool call) but gives no explicit exclusions or prerequisites beyond needing a key.

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 only readOnlyHint available in annotations, the description carries real extra weight: it explains that assist ops run on server-side small models rather than the caller's tokens, that the balance is debited by those ops, where credits originate (coupons or top-ups), and that exhaustion responses embed a top_up object with pay links. That is operational behavior an agent could not derive from the annotations or the empty 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 sentences, front-loaded with the purpose, then the mechanism (server-side models, balance debit), then the credits-source and exhaustion path. No filler, and every clause conveys something the agent acts on.

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

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

There is no output schema, so the description supplies the missing return-value information: the top_up object with pay links appears on zero balance or credits_exhausted. Combined with the annotation-declared read-only nature, an agent has everything needed to call and interpret this tool.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; a baseline of 4 applies. The description correctly does not invent parameter guidance.

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 ('Check the user's XeoRank Assist credit balance') and names the exact concept — Assist credits — that separates it from siblings like assist_savings or get_usage. It also names the sibling operations that consume the balance (assist_classify_keywords), so the agent can place it in the workflow without opening any schema.

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

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

It gives clear context for when the tool matters: when a balance is 0 or an assist op returns credits_exhausted, and it points to assist_redeem_coupon as the credit source. It stops short of an explicit 'call this before/after running an assist op' directive, so the invocation trigger is implied 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 already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered structurally. The description adds valuable beyond-schema context — cost (~1 Assist credit/keyword) and that results are stored — but does not clarify what the destructiveHint actually destroys (e.g. whether existing intent/funnel values are overwritten when store=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?

Front-loaded with the core action and the token-saving rationale, and each sentence carries signal (what it classifies, the omit-default, the cost, the sibling preference). Slightly padded by the 'saves your own tokens' framing, but overall tight.

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

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

For a mutation tool with no output schema but full annotation coverage, the description covers purpose, storage behavior, cost, and the sibling alternative, which is nearly everything an agent needs. It stops short of explaining the destructive/overwrite semantics flagged by the annotations.

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 already documents all four parameters including the 'omit to classify all unclassified' behavior of keywords. The description largely restates that, adding no syntax or format detail beyond the schema, so the 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+resource ('Classifies intent, funnel_stage, and cluster_name for tracked keywords') and immediately distinguishes itself from the sibling by explaining it is a server-side offload rather than local reasoning. An agent can tell it apart from classify_tracked_keywords without opening either schema.

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

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

Gives an explicit routing rule: 'prefer this over classify_tracked_keywords when a balance is available,' plus the operational condition 'Omit keywords to classify every unclassified tracked keyword.' It names the alternative and the selecting condition, leaving little to inference.

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

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

Adds genuinely useful traits beyond the annotations: server-side with no browser, pre-apply (non-mutating analysis), and a cost signal (“Costs a few Assist credits”). The only gap is that the description does not reconcile with the odd destructiveHint=true in the annotations, though it never claims to modify anything, so there is no real 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 verb+resource, then the specific defect classes, then the invocation window. It is long and dense, but nearly every clause carries information the agent needs to know what will be flagged.

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

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

There is no output schema, so the description does the work of explaining what findings look like — the defect names and what each means (row_without_breakpoint, sibling_drift). Combined with the cost and execution-model notes, an agent has what it needs, though it never says whether results are returned as a pass/fail list or detailed issues.

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 two parameters (site_id, post_id) are documented in the schema itself. The description adds no syntax, format, or constraint detail for them, 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 (“structural lint of a WordPress page”) and enumerates exactly what it flags (Pro-widget use, deep nesting, empty bands, section bloat, row_without_breakpoint, sibling_drift). An agent can distinguish this from generic page tools like assist_page_digest or wp_compare_pages without opening a schema.

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

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

Gives clear timing guidance: “Run it after building a section and before you publish.” That establishes context, but it never names an alternative (e.g. design_recommend or assist_page_digest) or states when NOT to use it, so it stops short of explicit routing.

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 cover safety flags (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true). The description adds real behavior the annotations cannot: it refuses with needs_author_material, loops review→revise until no blockers/cadence findings and voice in range, appends a disclosure line, and requires Pro + Assist credits. It stops short of stating persistence/reversibility of the saved draft, but the disclosure and refusal semantics are substantial additions.

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 hardest constraint (LAST-RESORT, Pro + Assist credits) and the material requirement, followed by refusal behavior, then the escalation condition. Dense but every clause carries distinct information; only the nested parentheticals slightly reduce scanability.

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, open-world writer tool with no output schema, the description covers prerequisites (author material, Pro + Assist credits), refusal behavior, the revision loop, side effects (disclosure line, saved draft), and the human-review boundary. An agent has everything needed to decide and invoke correctly.

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

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

Schema description coverage is 100%, so all three parameters are already documented. The description contextualizes max_passes (the review→revise loop) and save (the appended disclosure/stored draft), but adds no syntax, ranges, or defaults 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 (drafts) and resource (the brief's piece) with a precise input constraint (from the AUTHOR'S OWN MATERIAL — interview answers and/or rough draft). It explicitly distinguishes itself from the sibling score_content_draft and from the default writer role, so an agent can place it 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 an explicit escalation trigger: 'use this when a draft has failed score_content_draft twice or the user asks for it,' plus the self-label 'LAST-RESORT WRITER.' It also states the negative condition (refuses when the brief has no author material), which is the strongest form of when-not 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 flag destructiveHint=true and non-idempotence; the description goes further by disclosing the credit cost, the round-trip-checked and write-gated write path, and the dry_run escape hatch. It also clarifies the division of labor (agent orchestrates; service reads, generates, writes), which is behavior an agent cannot infer from the schema.

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

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

Front-loaded with the verb and differentiator, then prerequisites and cost. The 'You orchestrate; XeoRank reads+generates+writes.' line is slightly rhetorical but does encode the responsibility split, so almost every sentence earns its place.

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

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

With no output schema and a destructive, credit-metered write, the description covers the workflow, id sourcing, preview, gating, and cost. It does not spell out failure/rollback behavior or the write-enablement prerequisite implied by 'write-gated' (cf. wp_enable_writes), leaving a small gap for 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: where node_id comes from (assist_page_digest), the natural-language register expected for instruction (with worked examples), and the preview semantics of dry_run. That is above the baseline without being exhaustive.

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

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

States a specific verb+resource ('EDIT a page element') plus the key differentiator: intent-based rewriting with no HTML handling on the caller's side. It also names the mechanism (server-side read, small-model rewrite, validated patch) that separates it from sibling writers like wp_patch_page or wp_replace_section.

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 a concrete prerequisite ('Get element ids from assist_page_digest'), a safe-preview path (dry_run=true), and the cost implication ('Costs Assist credits'). It stops short of an explicit when-not-to-use or a named alternative for direct HTML editing, so it is strong 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 declare readOnlyHint=true and openWorldHint=true, so the description is not carrying the safety burden. It adds genuinely useful context the annotations cannot convey: that the call consumes Assist credits and what the ~1KB payload contains. It does not, however, discuss failure modes or the cost magnitude.

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 key differentiator ('OFFLOAD reading a WordPress page') and stays tight overall. The parenthetical aside about wp_get_page's cost is slightly verbose but earns its place by justifying the tool's existence.

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

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

With no output schema, the description carries the return-shape burden and does so precisely: semantic section types, one-line summaries, flat editable-element skeleton, and SEO gaps. An agent knows both inputs and outputs before calling.

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 site_id and post_id (with their provenance hints) are already fully documented. The description adds no syntax or format detail beyond what the schema provides, 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 (read a WordPress page as a compact digest) and explicitly contrasts itself with the sibling wp_get_page. The output contents (sections, editable-element skeleton, SEO gaps) make the tool's scope unmistakable.

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

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

Gives an explicit when-to-use (instead of wp_get_page) and names concrete next-step tools (assist_edit_section, wp_patch_page) that consume the element ids. The routing logic from digest to edit is spelled out, leaving nothing to inference.

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

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

Annotations already declare this is a destructive, non-idempotent, open-world write, so the safety profile is covered. The description adds genuinely useful behavior the annotations don't: the credit effect on the user's balance and the per-user-per-code rate limit. It omits error behavior for invalid, expired, or already-redeemed codes, keeping it out of 5 territory.

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

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

Two sentences, both carrying weight: the first states action, source example, effect, and limit; the second states the trigger. The action leads and nothing is repeated from the schema or annotations.

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

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

For a one-parameter mutation with full annotation coverage and no output schema, the description covers action, effect, frequency limit, and call trigger. The remaining gap is failure handling — what to tell the user when a code is invalid or already redeemed — which an agent would have to discover at runtime.

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

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

Schema coverage is 100% and the schema already documents the single `code` parameter including case-insensitivity, so the baseline is 3. The description adds provenance context ("e.g. one shared at a XeoRank workshop") that helps the agent recognize what a valid code looks like, a modest but real addition.

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 ("Redeem an Assist credit coupon code") plus the observable effect ("adds credits to the user's balance"). No sibling tool does anything similar — assist_balance and assist_savings are read-oriented — so an agent can select this without ambiguity.

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 condition ("If the user mentions having a code, redeem it for them") and a constraint ("Once per user per code"). It stops short of stating when NOT to call it or naming the alternative for balance/credit questions (e.g. assist_balance), but the positive routing is unambiguous.

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, so the read-only nature is covered; the description adds useful semantic detail on what is counted as "saved" and how it was offloaded. It does not address the surprising destructiveHint=true flag on what is clearly a reporting operation, nor does it describe return format. With annotations carrying the safety profile, a 3 is appropriate.

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

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

Two sentences, front-loaded with the primary output and followed by the single usage condition. No filler; every clause carries information.

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

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

With no parameters and no output schema, the description compensates by enumerating the three reported metrics, so an agent knows what it gets back. It is complete for the call itself, missing only any note about the anomalous destructive annotation.

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

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

The tool takes zero parameters and schema coverage is 100%, so the baseline is 4. The description usefully clarifies the semantics of the reported values (own tokens saved, credits spent, spend avoided), which is more than the empty schema conveys.

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 specific verb (Report) and the precise resource set it produces: agent tokens saved, credits cost, and estimated large-model spend avoided. The parenthetical mechanism (server-side offloading of reads/edits/classification) makes the scope concrete. It does not name a sibling to differentiate from, 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?

"Use it to show ROI after a session" gives a clear triggering context for the tool. However, it names no alternative (e.g. assist_balance or get_usage) and states no exclusions, so it is a solid context statement rather than explicit when/when-not 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?

With annotations covering read-only, open-world, non-idempotent, and destructive flags, the description still adds real value: it discloses the credit cost, that execution is server-side with 'no page changes', and that the output is a graded, severity-ranked report with fixes. The 'Read-only / no page changes' claim matches readOnlyHint=true but sits uneasily next to destructiveHint=true in the annotations, a tension the description does not address.

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

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

Two sentences, both front-loaded: the first names the operation, scope, and full check list; the second covers return shape, execution model, and cost. No filler or restated boilerplate — every clause carries information.

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

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

For a single-parameter, no-output-schema tool, the description is nearly complete: it explains what is inspected, what is returned (A–F grade, severity ranking, concrete fixes), how it runs, and that it consumes credits. It could go slightly further on cost magnitude or prerequisites (e.g., that the site must be connected first), but nothing essential is missing.

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

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

There is a single parameter and schema description coverage is 100% — the schema already documents site_id as a connected WordPress site UUID sourced from list_wordpress_sites. The description adds nothing about the parameter, so the baseline 3 for fully-covered schemas 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 ('Read-only WordPress security posture audit of a connected site') and then enumerates the exact checks performed (core-version currency, plugin/theme inventory, user-enumeration, XML-RPC, version-leak files, headers, directory listing). This clearly separates it from sibling WordPress tools like get_site_health, technical_health, or wp_capabilities without needing to open any schema.

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

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

It gives useful context for invoking it — the site must be a connected WordPress site, it runs server-side, and no wp-cli/SSH is required — plus a cost warning. However it never routes the agent between this and adjacent tools (technical_health, get_site_health, plan_search_audit), and gives no when-not conditions, so usage is implied rather than directed.

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 destructive=true, non-idempotent, open-world, but the description adds substantial context beyond them: server-side reading of every text field, HTML preservation, application via the validated patch path, and a credit model where dry_run previews are free while real apply debits credits. These are exactly the behavioral traits an agent needs before invoking a destructive mutation.

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

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

The core purpose is front-loaded in the first clause, followed by examples, mechanics, and cost guidance in a logical order. It is dense with em-dash clause stacking but every sentence carries actionable information, so almost nothing is wasted.

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

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

For a destructive mutation with no output schema, the definition covers scope, mechanics, cost behavior, and the dry-run workflow thoroughly. It does not describe what a real (non-dry-run) apply returns or how to verify the result, a minor gap given the absence of an output schema.

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 slightly exceeds it by reinforcing that dry_run is the preview-plus-cost-estimate path and that instruction is a high-level intent rather than a literal string. It stops short of adding new semantics not already in the schema, so it is a modest addition over the structured 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 description names a specific verb (transform) and resource (a page's text) driven by a high-level instruction, with concrete examples ('respecialize this urology page to pulmonology'). It explicitly distinguishes itself from the sibling wp_patch_template for header/footer/single-template edits, so an agent can route without opening a schema.

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

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

It states when to use it ('best for making a cloned page genuinely about a different topic'), a mandatory workflow step ('use dry_run=true FIRST'), and names the alternative (wp_patch_template) with the condition that selects it. When-to-use, when-not, and alternatives are all covered.

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?

Despite annotations already declaring readOnlyHint, the description adds substantial behavioral context: server-side registry read, verification that every returned key exists, invented names dropped and surfaced under dropped_not_in_registry, and a credit cost versus a free sibling. It also warns keys are non-obvious (text_align, end), which shapes how an agent interprets results.

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

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

Front-loaded with the core question and answer shape, and most sentences carry decision-relevant information (cost, verification, non-obvious naming). It is slightly long and rhetorically framed, but no sentence is pure 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?

No output schema exists, so the description carries the return-value burden and does: 2-3 verified keys plus a dropped_not_in_registry list. Combined with cost and verification semantics, an agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100%, so the baseline is 3. The description still adds meaning by explaining that a widget registry can exceed a thousand controls with responsive variants and that 'container' is passed for sections — context the schema alone hints at but does not convey in terms of scale and cost.

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 precise verb+resource ('give a widget and what you want to change; get back the 2-3 REAL control keys') and explicitly distinguishes itself from the sibling wp_widget_controls by framing this as an answer rather than a catalogue. An agent can tell the two apart without opening either schema.

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

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

Names the alternative (wp_widget_controls) and the exact condition that selects this tool over it ('when you want an answer rather than a catalogue'), plus the cost trade-off. When-to-use is fully specified.

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

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

Annotations cover safety (readOnlyHint=true, destructiveHint=false), and the description adds substantial context beyond them: never applies anything, never invents numbers/sources/quotes, unsourced claims get qualified/marked/removed, unanchored patches are dropped, digit-introducing patches are flagged, and it discloses fixed cost per call up to 12 findings with free clean text.

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

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

Front-loaded with the core purpose and dense with substance; nearly every clause earns its place (constraints, workflow, cost). Some sentences are run-on and pack multiple behaviors, but there is little waste.

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

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

No output schema, yet the description explains what the tool returns (patches with their 'why'), how they should be applied, and the cost model. For a read-only proposal tool with full schema coverage, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning for otherwise opaque params: findings defaults to running the detector, max_findings is capped at 12, and site_id drives cost attribution. It elaborates on the cost model tied to the findings parameter.

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

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

States a specific verb+resource ('proposes the SMALLEST find→replace patches') and names the sibling findings sources it resolves (review_writing / score_content_draft). It also distinguishes itself from the editor-model alternatives by noting 'not the lite tier' and 'never rewrites the document' vs rewrite_content.

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: invoke after review_writing/score_content_draft findings exist, and the full workflow ('Show the user each patch... then review_writing again'). It stops short of explicitly naming rewrite_content as the alternative for full rewrites, so the sibling routing is implied 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 declare destructiveHint=true, openWorldHint=true, idempotentHint=false, yet the description portrays a purely informational 'ask questions' interaction and never warns that the chat may modify state or take actions. It also omits any statement about conversation persistence or whether prior turns are retained across calls, which matters for a non-idempotent chat 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?

Two short sentences, purpose front-loaded, and the second sentence adds concrete use cases rather than filler. Nothing is wasted.

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

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

For a two-parameter, no-output-schema tool the description is adequate on intent, but given the destructive/openWorld annotations it should say what the call actually returns or whether it can alter the audit. An agent can call it correctly but cannot predict its effect.

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

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

Schema description coverage is 100% and both parameters are already documented ('Your question or message about the audit', 'The audit ID'). The description adds no format, length, or contextual constraints beyond what the schema states, 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 interaction (conversing with an AI) bound to a specific resource (an audit's findings) and enumerates the kinds of exchanges supported. It is clearly distinct from siblings like get_audit or get_audit_report, though it never contrasts itself with the other chat-style sibling (keyword_chat).

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

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

It implies when to use it (you have an audit and want to ask about issues, guidance, or priorities), which is decent implied usage. But there is no explicit when-not guidance, no prerequisite (e.g. an existing completed audit), and no routing versus list_audits/get_audit_report.

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, destructiveHint=false and openWorldHint=true, so the safety and read-only profile is covered without description help. The description adds only the purpose-level claim about indexing status; it does not mention rate limits, what happens when some URLs fail, or that idempotentHint=false means repeat calls may return different results.

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, purpose first, differentiation second, and every clause carries information. Nothing is repeated from the schema or the title.

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, three-parameter inspection tool with full schema coverage and annotations covering safety, the description covers what the tool does and when it beats the alternative. The remaining gap is return-shape and partial-failure behavior, which is modest given the absence of an output schema and the low complexity.

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

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

Schema description coverage is 100%, so the meaning of site_id, urls and detail (including the concise/detailed behavior) is fully documented in the schema. The description adds no parameter-level semantics beyond the schema, which is exactly the baseline 3 case.

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 (inspect), resource (multiple URLs), and outcome (indexing status and issues), so the agent knows exactly what it gets back. It implicitly separates itself from the single-URL sibling by contrasting with 'inspecting one at a time', though it never names inspect_url or get_url_inspections 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?

The phrase 'More efficient than inspecting one at a time' gives an implied usage rule (use this when you have several URLs), which is better than nothing. However, it never names the alternative tool (inspect_url) or states the boundary conditions — e.g. that a single URL should go elsewhere, or that batches are capped at 50 (that constraint only lives in the schema).

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: per-keyword cost (~$0.015), the >8-keyword background threshold, the returned status=started with run_id and estimated_seconds, and the async polling contract via list_tracked_keywords.last_check.status. It does not explain why the tool is marked destructiveHint=true/non-read-only (account spend, mutating last_check state), which is the one behavioral trait an agent might not anticipate.

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

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

Two tight sentences, front-loaded with purpose and cost, then the prerequisite, the async behavior, and the do-not-recall warning in order of operational need. Every clause carries information an agent must act on.

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

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

No output schema exists, yet the description fully compensates by describing the immediate return (status=started, run_id, estimated_seconds) and the terminal states (running → completed | partial | failed with the error) read elsewhere. Nothing needed to call it correctly or interpret its result is missing.

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

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

Schema description coverage is 100% and the single parameter (site_id) is fully documented in the schema, so the baseline is 3. The description implies scope ('all tracked keywords') but adds no syntax or format detail beyond what the schema already provides.

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

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

States a specific verb and resource ('Live rank check for all tracked keywords against the brand's ranking location') and scopes it to the brand's ranking location. An agent can separate it from siblings like tracked_keyword_performance, keyword_competitor_ranks, or set_ranking_location 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 prerequisite ('set_ranking_location first'), an explicit exclusion ('Do not call again while it is running'), and routes the agent to the right alternative for results (list_tracked_keywords). Nothing about when to invoke or avoid it is left to inference.

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

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

Annotations already declare readOnly=false, destructive=true, idempotent=true, openWorld=true, and the description adds real behavioral context: matching is done by keyword text, ranking_url is ignored unless it is on the site's own domain, and Xyle records rather than generates classifications. It never spells out what a re-run overwrites for already-classified keywords, which is the main gap against the destructive hint.

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

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

Front-loaded with the core action, then definitions, example, matching behavior, and trigger, in a logical order. Dense but almost every clause carries information; it is on the long side but contains no padding.

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

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

For a 2-parameter, high-coverage mutation tool with no output schema, the description covers field semantics, invocation format, matching behavior, correction semantics, and a trigger. It omits return-value expectations and permission/auth requirements, which keeps it short of fully complete.

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

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

Despite 100% schema coverage, the description supplies semantics the schema lacks — there are 0 enums in the schema, yet the description defines allowed intent values (informational/commercial/transactional/navigational), funnel_stage meanings (tofu/mofu/bofu), cluster_name conventions (2-4 words, reused, aim 5-15 clusters), and a concrete JSON payload example. This meaningfully exceeds 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?

States a specific verb and resource — storing your own keyword classification onto a brand's tracked keywords — and draws a clear boundary against the agent's own reasoning ('Xyle records — it does not classify for you'). This distinguishes it from add_tracked_keywords and assist_classify_keywords, which an agent could otherwise 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?

Gives concrete triggers: 'run after adding keywords or when get_keyword_funnel reports unclassified ones,' and names get_site_journeys as the signal for using ranking_url to correct a mapping. It stops short of explicitly excluding the similar assist_classify_keywords sibling, so the agent must infer when to prefer one over the other.

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 openWorldHint=true, so the description needn't restate safety. It adds real behavioral context beyond them: the lazy/cheap-first retrieval strategy, the cost signal on errors_only, and the anti-pattern warning against full-log dumps. It does not explain truncation behavior (what happens when the tail is cut off mid-stream), which is the remaining behavioral gap. Note the annotation set itself is internally odd (destructiveHint=true alongside readOnlyHint=true), but the description's 'fetch' framing is consistent with readOnlyHint, so this is an annotation inconsistency rather than a description 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 core action, then the workflow pointer, then the retrieval policy. Every sentence earns its place and nothing is padded; the telegraphic 'LAZY:' framing is intentional signaling rather than noise.

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

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

No output schema exists, and the description covers the essential shape (a small tail of build log events, error/warning lines when filtered) plus the diagnosis-then-fix workflow and cost discipline. Only the truncated-tail case is unaddressed; everything an agent needs to call it correctly is present.

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

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

Schema coverage is 100%, so the schema already documents limit (default 25, max 100) and errors_only. The description still adds decision semantics the schema lacks: when to prefer errors_only=true (first, cheap) and when limit is worth raising (only if the error-only tail is insufficient). That is added meaning, not repetition.

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+scope: 'Fetch a SMALL tail of Vercel build log events for a deployment.' It also positions itself in the workflow by naming code_deploy_status as the source and code_write_files as the follow-up, so an agent can distinguish it from those 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 when-to-use and how-to-sequence: diagnose a failure here, then fix with code_write_files; 'prefer errors_only=true first'; 'only pull more with limit if needed'; and an explicit exclusion, 'Never dump a full build log.' This is a complete usage policy, not implied guidance.

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

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

Annotations cover the safety profile (readOnlyHint, openWorldHint), and the description adds genuinely new behavioral context beyond them: the push-triggered deploy model, the correct call sequence after code_write_files, and the state/target semantics that determine prod_url. It leaves one gap: the annotations declare destructiveHint=true while the operation reads as a pure query, and the description does nothing to explain that discrepancy.

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 is returned, when to call it, and how to interpret the result. The core verb and resource are 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?

No output schema exists, so the description must carry the return shape, and it does summarize it (state, url, target, prod_url). It is nearly complete for a one-parameter read tool, though it omits whether polling/retry is expected while a build is pending.

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

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

With a single parameter and 100% schema description coverage, the schema already carries the meaning of site_id. The description adds no format, id-source, or lookup guidance beyond it, 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 ("Get the latest Vercel deployment for a code site") and even names the returned fields (state, url, target), so an agent can distinguish it from siblings like code_status, code_build_logs, or code_write_files.

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 triggering context: "Deploys are push-triggered, so call this after code_write_files to watch the build." It does not, however, name an alternative (e.g. code_build_logs for logs) or state when not to use it, so it stops short of the explicit when/when-not/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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is partly covered; the description usefully adds that it returns commands and never touches the user's filesystem, plus the git->push->Vercel auto-build sync model. However it never addresses the destructiveHint=true flag, leaving an unresolved tension an agent must guess about, and it says nothing about permissions or platform 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?

Three sentences, front-loaded with the action and its output, then usage context, then the sync model and scope caveat. No filler, though the parenthetical list partially repeats the clone concept and the final disclaimer sentence could sit earlier.

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

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

For a one-parameter tool with no output schema, the description covers what is returned (commands), when to invoke it, and its boundaries. The only gap is the shape of the response (single command block vs. per-platform steps) and the unexplained destructive annotation.

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% for the single site_id parameter, so the schema fully documents it and the description adds nothing about the parameter (e.g. where to obtain a site id). Per the high-coverage baseline, 3 is the correct score.

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

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

States a specific verb and resource ('Get the exact commands to clone a code site onto the user's LOCAL machine') and enumerates the delivered artifacts (clone, install, dev server, push-to-deploy, branch flow). This is clearly distinguishable from siblings like code_write_files (which mutates the site) or list_code_sites (which enumerates).

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: 'Use when the user wants to work locally with their own Claude/Codex.' It also carves out scope ('XeoRank only helps set up the local drive; it does not touch the user's filesystem'). It does not name a competing sibling tool or say when NOT to use it, so it falls short of a 5.

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

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

Annotations already disclose that this is destructive (destructiveHint=true), mutating (readOnlyHint=false), and non-idempotent, so the safety profile is covered. The description adds the useful return-behavior detail "Returns verification records if DNS setup is needed," which helps the agent anticipate response content, but doesn't cover auth, reversibility, or side effects on existing domains.

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 concise sentences with zero waste; the core action is front-loaded and the return behavior follows naturally.

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, non-idempotent operation with no output schema, the description should cover more: what happens to an existing domain (replacement/conflict), required permissions, or that the action cannot be undone. It states the purpose and a partial return behavior but leaves meaningful operational gaps.

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

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

Schema description coverage is 100%, with both parameters documented ("Domain to attach (e.g. mysite.com)" and "Code site id"). The description does not add syntax, format, or 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 delivers a specific verb and resource ("Attach a domain to a code site's Vercel project"), clearly distinguishing it from siblings like connect_vercel, vercel_link, and code_set_public. An agent can identify its exact operation from the text alone.

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 guidance on when to use this tool versus alternatives such as vercel_link or connect_vercel, nor any prerequisites or exclusions. The agent must infer usage from the name and description alone.

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, openWorldHint=true, and idempotentHint=false, so the safety profile is carried structurally. The description adds useful state context (default-public behavior for new sites, reversibility of the lock), but it never explains why destructiveHint is flagged or what exposure making a site public creates. Adequate but not rich 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?

Two sentences, zero filler, with the primary action and the default-state caveat front-loaded before the when-to-use routing. Every clause carries 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 two-param toggle with no output schema and rich annotations, the description covers purpose, trigger, inverse case, and default behavior. It lacks only the return/confirmation behavior and any propagation delay note, which keeps it short of a 5.

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%: both site_id and the public boolean are already documented inline with the same true/public, false/auth mapping. The description restates 'public=false' semantics without adding format or edge-case detail, 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 (make publicly accessible / re-protect) and resource (code site), and names the concrete mechanism (disable Vercel Authentication). An agent can distinguish this from code_set_domain, code_status, or delete_site 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?

Explicitly gives the triggering condition ('when a site shows a Vercel login/SSO screen instead of loading') and the inverse case ('to lock a site behind auth (public=false)'). It also pre-empts a likely misuse by noting new sites are already public by default, so the tool need not be called for them.

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

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

Annotations already carry the full safety profile (readOnlyHint, openWorldHint, destructiveHint, idempotentHint), so the description's added burden is lower. The description adds a useful cost hint ('cheap') and sketches the return shape (current step + next_step), but it does not address the surprising destructiveHint=true, leaving an unexplained behavioral flag. Value added is real but modest against a rich annotation set.

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

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

Two tight sentences, front-loaded with the core summary ('Cheap flow check') followed by the output shape and the usage directive. Every clause earns its place with no filler or restated metadata.

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

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

There is no output schema and no parameters, so the description must carry the return-value burden — which it does by naming the connected-status flags and the `flow` object with current step and `next_step`. It is complete enough to invoke correctly, though the exact shape of `flow` is only described at a high level.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to disambiguate, and it correctly spends no words on parameter 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 purpose: a status/flow check reporting whether GitHub/Vercel are connected plus a `flow` object with the current step and `next_step`. It distinguishes itself from the many sibling listing tools (list_code_sites, github_list_repos) by explicitly framing itself as a single orientation call rather than a re-listing operation. The jargon ('flow object', 'nudge') slightly muddies the verb, keeping it from a clean 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 gives an explicit usage rule — 'Call this ONCE to orient instead of re-listing repos/sites every turn' — which tells the agent both when to use it (orientation) and what not to do (repeated listing). It stops short of naming the alternative tools by name, so an agent still has to infer which siblings this replaces.

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 destructiveHint=true, idempotentHint=false, and openWorldHint=true. The description adds concrete behavior beyond them: writes always target the default branch with no branch choice, existing files are overwritten, and a Vercel deployment side effect fires in the same call. It omits permission/auth requirements and error behavior.

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

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

Three tightly packed sentences with the action and overwrite semantics front-loaded, then the input format, then the side effect and next step. No filler or restated 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?

With no output schema, the description carries return-value burden and does mostly well by pointing to code_deploy_status for the deployment outcome. It leaves unstated what the commit confirmation looks like and what happens on failure, but an agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the `files` format (JSON array of path/content) already documented in the schema and never explains message or site_id, adding no meaning beyond the structured 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?

States a specific verb and resource (commit files to a code site's repo), specifies the scope (single commit), and clarifies create-vs-overwrite semantics. An agent can distinguish it from siblings like code_deploy_status, github_create, and the wp_* write tools 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 clear operational context: files go to the default branch, and for Vercel-linked sites a deploy is triggered in the same call, so the agent should poll code_deploy_status afterward. It names the follow-up tool explicitly, but offers no explicit when-not or guidance on choosing this over github_create/wp_update_page for other site types.

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 (readOnly=false, idempotent=false) by disclosing the metered cost model, per-plan allowances, the unit-per-page+keyword accounting, the partial-result behavior when the cap is hit (finished gaps kept, cap_reached true), and the internal page-selection heuristic. This is unusually rich operational context for a mutation-style 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?

Long but dense and front-loaded: purpose first, then cost model, then on-demand constraint, then selection heuristic, then dry_run/result guidance. Every sentence carries distinct information, though it could be trimmed slightly.

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

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

No output schema exists, yet the description covers where results land (get_competitive_landscape -> content_gaps), the partial-cap caveat, and the cost, which is everything an agent needs to invoke and report correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds meaning by tying each analysis to a unit cost and clarifying that dry_run spends nothing while limit caps the pairs analysed. It reinforces rather than merely repeats 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 ('work out which topics rivals cover that this site's own ranking pages do not') and names where the output goes, distinguishing it from read/analysis siblings. An agent can tell what it 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?

Explicit when-to-use: 'Deliberately on-demand — nothing computes gaps on a schedule, so call this when the user actually wants the answer.' It also directs the agent to run dry_run first and to fetch results later for free via get_competitive_landscape, naming the alternative consumer.

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 only basic annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false), the description carries the behavioral burden well: it discloses that the key is validated and stored encrypted, that a framer_site_id is returned for downstream framer_cms/framer_canvas/framer_publish, that re-connecting updates the key, and that a missing site_id yields a warning. No contradiction with 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?

Dense and front-loaded — the server-side scope and the sibling distinction come first, then setup steps, then the return value and the no-arg list mode. The parentheticals are informative rather than filler, though the run-on density is slightly heavy.

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

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

No output schema exists, yet the description names the key return value (framer_site_id) and its consumers, documents the zero-argument list behavior, and supplies the user-facing prerequisite flow. Nothing an agent needs to invoke or sequence this tool is missing.

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

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

Schema coverage is already 100%, but the description adds relationship-level meaning the schema states only per-field: the strongly-recommended site_id binding and its consequence (warning + inability to join crawl/audit/AI-visibility data), domain as an alternative to site_id, and the key+project pairing workflow. This exceeds the baseline 3 for full-coverage schemas.

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 ("Connect a Framer project") and immediately scopes it to server-side editing, explicitly distinguishing itself from Framer's editor-bound MCP plugin and implicitly from the other connect_* siblings. An agent knows exactly what this tool does and what it is not.

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

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

Gives concrete operational steps for when to use it: ask the user for an API key via the named Framer UI path, paste key with project URL, and call with no arguments to LIST already-connected projects. It does not name a competing sibling (e.g. connect_wordpress/connect_vercel) or state an explicit when-not condition, so it falls just short of the top tier.

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 is a non-read-only, idempotent, open-world operation, so the safety bar is lowered. The word 'flow' usefully signals an interactive/redirect-based auth exchange, which annotations do not convey, but the description never discloses the destructive consequence declared by destructiveHint=true (e.g. overwriting or replacing an existing GA connection).

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?

A single front-loaded sentence naming the verb and resource with no filler. It is efficient, though so terse that it omits information the six dimensions above show is missing.

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 state-mutating, open-world connection tool with destructiveHint=true and no output schema, the description says nothing about preconditions, what the returned flow requires, or what existing data may be affected. An agent could call it correctly but not safely.

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 site_id and property_id are already documented in the schema, and the description adds nothing about their format or relationship (e.g. that the property must belong to the site). Baseline 3 applies when the schema carries parameter meaning.

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

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

States a specific verb ('Initiate') and resource ('Google Analytics connection flow for a site'), which separates it from connect_google_ads, connect_framer, connect_github and the other connect_* siblings by resource. It is clear but does not explain how it differs from the read-side siblings like get_ga_status.

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

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

There is no guidance about when to use this tool versus an alternative, no mention of prerequisites such as a connected site or an existing OAuth session, and no note on what to do if a GA connection already exists.

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 the mutation profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true), so the description earns credit for adding the OAuth mechanics, the fact that the token is stored automatically with 'no paste', and the sequencing constraint of polling code_status. It does not explain why destructiveHint is set (e.g. what a reconnect does to an existing token), which is the only real gap.

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

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

Three sentences, front-loaded with the primary no-argument flow before the fallback, and no filler. The parenthetical fallback is slightly dense but keeps the main path readable.

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

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

With no output schema, the description helpfully names the returned `auth_url` field the agent must present, names the prerequisite and the verification step, and covers both connection paths. Complete enough for a one-optional-param connector; only the return shape beyond auth_url is 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% and the sole parameter is optional, so the schema already documents `token`. The description adds marginal value by framing it as an 'advanced fallback ... without the browser flow', but offers no format or scope details beyond that. Baseline 3 is appropriate when the schema does the heavy lifting.

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 ('Connect the user's GitHub account') and scopes it to 'code sites', which separates it from the many sibling connectors (connect_vercel, connect_ga, connect_framer, connect_wordpress). An agent can route to it 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?

It is explicit about the default path (call with NO arguments), the exact user flow (click link, approve on GitHub, token auto-captured), the prerequisite (site registered via create_site), and the follow-up (poll code_status). It even names the advanced alternative (PAT via `token`) and when to use it.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is partly covered. The description usefully adds the downstream consequence that Keyword Planner data activates on completion, but it never explains the destructive aspect, the link's expiry/reuse behavior, or what happens if the site is already connected — the tension between 'Get the OAuth link' and destructiveHint=true is left unaddressed.

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

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

Two tight sentences with the purpose front-loaded; the second sentence delivers real context rather than filler. 'Xyle's developer token is approved' is slightly promotional and could be trimmed, keeping it just short of a 5.

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

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

For a one-parameter connect tool the definition tells the agent what it returns (an OAuth link), what it connects (Google Ads to a site via site_id), and the payoff after the handshake. With no output schema required for such a simple flow, nothing essential is missing for a correct invocation.

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

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

Schema coverage is 100% for the single site_id parameter, and the description neither names it nor adds format/constraint detail beyond the schema. Baseline 3 is appropriate when the schema fully carries the parameter documentation.

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

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

The description names a concrete verb and resource: it returns an OAuth link so the user can connect a Google Ads account to a site. That is far more specific than a tautology, and the effect (Keyword Planner activation) rounds out the purpose. It does not, however, explicitly contrast itself with the nearby get_google_ads_status or the other connect_* siblings, so differentiation relies partly on the tool name.

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

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

Usage is only implied: the agent can infer 'use this to connect Google Ads,' but there is no statement of when to call it versus checking existing status (get_google_ads_status) or reconnecting an already-linked site. No prerequisites or exclusions are mentioned, leaving the routing decision to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true, so the safety profile is covered. The description adds real value beyond them: the OAuth approval happens on Vercel, the token and team are captured and stored automatically with no paste, and the agent must poll code_status afterwards. It does not explain what an existing connection being overwritten would mean, despite 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?

Front-loaded with the primary action ('Call with NO arguments') and the fallback is clearly parenthesized as secondary. Dense but nearly every clause earns its place; the ellipses and stacked asides are slightly informal for a tool definition.

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

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

With no output schema, the description usefully names the returned auth_url field and the follow-up code_status poll, which is exactly what an agent needs to complete the flow. It stops short of describing success/error outcomes or what the tool returns in the token-fallback path.

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 both parameters are already documented there, including that team_id is only used with the token fallback. The description restates the same fallback semantics, adding no syntax, format, or validation detail beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('Connect the user's Vercel account') and immediately distinguishes the two operating modes: no-argument OAuth flow versus the token fallback. An agent can tell this apart from generic account tools like vercel_link or connect_github 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?

It gives explicit operational guidance: call with NO arguments to get the OAuth link, present the returned auth_url, then poll code_status; use the token/team_id path only as an advanced fallback. It does not state prerequisites (e.g., needing an existing Vercel project) or contrast with the sibling vercel_link tool, so it stops short of a 5.

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

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

With no output schema, the description carries the full burden and delivers: it names the returned field (onboard_url), explains the downstream wizard behavior (installs connector plugin, opens wp-admin, completes automatically), and rules out the common alternatives (no Application Password, no follow-up call). This is rich behavioral context beyond the readOnly/destructive/openWorld 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 core action, then the required next step, then verification, then the edge case — a logical progression with no filler sentences. The all-caps emphasis and layered clauses make it slightly dense, but every sentence carries operational weight.

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 connection tool with no output schema, the description supplies the return value, the user-facing next action, the verification loop, and the transport edge case. Nothing an agent needs to invoke and then correctly handle the result is missing.

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

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

Schema coverage is 100%, so the structural baseline is 3, but the description adds real semantics: domain normalization ('https:// and www are stripped') and a usage condition for transport. Minor tension: the schema documents 'ssh' as the default transport while the description frames 'ssh' as a Hostinger-only fallback, which could mildly confuse an agent.

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 ('Connect a WordPress site to XeoRank') and immediately disambiguates from the crowding of connect_* and set_wordpress_connection siblings by describing the plugin-based onboarding flow. An agent can tell what this does and how it differs from the other connection tools 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?

Explicitly prescribes the post-call action ('PRESENT THAT TO THE USER AS A CLICKABLE LINK and stop there'), names the follow-up verification path (list_wordpress_sites or verify_wordpress), and gives a conditional exception (transport='ssh' only as a Hostinger fallback). When-to-use, when-not-to-act, and alternatives are all covered.

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 (which only flag it as a mutating, open-world, non-idempotent write), the description discloses concrete side effects: resolving or opening a brief, linking it to the goal, moving the goal to active, and returning the next loop step. It also warns that a derived keyword must be confirmed with the user. It does not describe failure modes or error behavior, holding it below a 5.

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

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

Front-loaded with the 'START HERE' trigger, which is exactly the right priority. The remaining content is dense but all relevant, though the second sentence runs long with several chained clauses that could be split for readability.

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

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

For a multi-step orchestration entry point with no output schema, the description covers the trigger, the state mutations, and the shape of the returned next_step (the full interview-to-outcomes loop), and tells the agent to follow it exactly. An agent has everything needed to invoke it and act on the result.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real meaning for target_keyword (it is derived from the goal title unless passed, and a derived keyword should be confirmed), which is semantic value the schema does not provide. It adds nothing for notes, goal_id, or site_id.

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 (resolves/creates a goal's content brief and returns the next loop step) and clearly scopes it to goals rather than pages, which distinguishes it from the sibling content_for_page and create_content_brief. An agent can tell what this does 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 phrase ('START HERE when the user says write the blog / page for this goal'), which is strong when-to-use guidance. It does not name the page-level alternative (content_for_page) or state when-not to use it, so it falls just short of a full when/when-not/alternatives statement.

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

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

Annotations already declare the safety profile (not read-only, not destructive, open world), so the bar is lower. The description still adds real side-effect context: it fetches the live page, saves the before-score and a 28-day GSC baseline, creates the brief draft, and clarifies the actual post write happens later via publish_content_brief — consistent with readOnlyHint=false.

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

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

The core directive is front-loaded in caps, followed by dense but relevant pipeline detail. It is long and clause-heavy, but for a complex orchestration tool most sentences carry functional information; some phrasing (author_draft/draft/front-matter) is packed tightly.

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

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

With no output schema, the description still explains what comes back (optimisation guidance with specific actions like keeping the URL, fixing title/meta on CTR lag, adding H2s) and how outcomes are read (uplift against the saved baseline). For a complex tool this covers what an agent needs to invoke and interpret it.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond it by explaining how the derived target is chosen (striking-distance GSC queries, positions 4–20, most impressions first) and that target_keyword overrides it, giving useful semantics for that field despite the schema already documenting it.

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

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

The description opens with a specific directive ('OPTIMISE A PAGE THAT ALREADY EXISTS') and scopes it to 'an existing blog or page', distinguishing it from new-content tools in the sibling set. It names the concrete resource (a live page) and the downstream action (publish_content_brief updates in place). An agent can identify the verb+resource 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?

It states a clear trigger — 'start here when the user wants an existing blog or page improved' — and gives the override escape hatch ('override with target_keyword'). It does not explicitly exclude the new-content alternative or name which sibling handles that case, so guidance is strong but not fully bounded.

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/openWorld, but the description adds that it is 'Free — reads stored data', discloses the return shape (evidence, impact_clicks, kind, trend, score) absent an output schema, and warns that a 0 source means the signal was never collected. It does not explain the internally inconsistent destructiveHint=true annotation, but it does not contradict readOnly either.

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 purpose and keeps every clause informational, but the single dense paragraph with nested parentheticals and caps-emphasis is heavy; splitting the signal list from the workflow guidance would read faster. Still, no sentence is filler.

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

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

For a no-output-schema, 4-param read tool this covers the essentials: what it returns conceptually, the kind/trend/score semantics, why trending items matter, the free/read nature, and dependency remediation. Grouping rules for 'several signals agree' are gestured at but the exact scoring mechanics remain implicit.

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 real meaning: it explains what the `trends` flag actually computes (live 28-day vs prior-28-day GSC windows for rising/new demand) and what limit/detail feed ('present the top few'). That is more than the schema's terse one-liners provide.

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 ('Rank what this site should write or improve next') and enumerates the exact signals it consolidates (GSC page-2/low-CTR queries, rising demand, content gaps, clusters without a ranking page, tracked keywords, AI-answer prompts). It distinguishes itself from siblings by naming the tools that feed it rather than produce the same output.

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?

Positions the tool explicitly in a workflow ('Start of the content_engine workflow: present the top few to the user and let them choose') and gives a presentation rule ('Lead with trending ones when presenting'). It also explains how to remediate empty signals by pointing at sync_search_console, compute_content_gaps, create_keyword_session, add_tracked_keywords and run_visibility_scan, though it never names a sibling to use *instead* when this tool is the wrong choice.

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 the safety profile (readOnly, openWorld, idempotent=false, destructive=true). The description adds genuine context beyond them: the checkpoint windows matter and the rank correlation only appears once 5+ pages share a checkpoint. It is silent, though, on the refresh side-effect and on why a reporting tool carries destructiveHint=true, so the behavioral picture stays incomplete.

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

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

Two sentences, front-loaded with the resource and metrics, then the action guidance. The first sentence is dense and clause-heavy but every clause carries information; nothing is padding.

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

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

With no output schema, the description does the work of describing returns (publish score vs clicks/position, correlation once 5+ pages qualify), which is the key thing an agent needs. It is only incomplete on the operational side (refresh behavior, destructive semantics) given the annotated hints.

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 site_id, checkpoint (14|30|60, default 30) and refresh. The description reinforces checkpoint meaning and the 5+ page threshold tied to it, but adds no syntax or default detail the schema lacks. Baseline 3 for a fully covered schema 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 resource (every published brief on a site) and the exact metrics produced (score at publish vs clicks/position at a checkpoint, plus rank correlation). This is far more than a restatement of the name. It only falls short of 5 because it never distinguishes itself from the close sibling get_content_outcome (singular), leaving the aggregate-vs-single-page scope to inference.

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?

"Use it to report content ROI and to decide what to write next" gives clear usage context. However, it names no alternative and sets no exclusions, so an agent cannot tell from the text alone when get_content_outcome or content_for_goal is the better pick.

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=false and openWorldHint=true, so the safety bar is lower. The description still adds real behavioral context beyond them: it resumes from a saved frontier (explaining the non-idempotent resume semantics) and consumes additional page budget. It does not clarify why the operation is flagged destructive, which is the remaining gap.

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

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

Two tight sentences: the precondition and core action are front-loaded, and the trailing sentence is an actionable next step rather than filler. No sentence 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?

With no output schema, the description compensates by telling the agent to poll get_crawl_status for results. For a 2-parameter mutation tool, precondition, action, and post-action are all covered.

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

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

Schema description coverage is 100% – both job_id and additional_pages (including the 500 default and plan-cap note) are fully documented in the schema. The description only alludes to the page limit, adding no syntax or semantics beyond the schema, so the baseline of 3 applies.

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

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

Specific verb (extend/resume) applied to a specific resource (a crawl), with the exact state precondition (status "partial", coverage.reason "page_limit_reached"). This cleanly distinguishes it from start_crawl (new crawls) and get_crawl_status (read-only polling).

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 a precise when-to-use condition via the status/reason pair and names the follow-up tool (get_crawl_status). It stops short of an explicit when-not-to-use (e.g., 'for new crawls use start_crawl', or behavior on failed crawls), so it is strong but not fully closed-loop.

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=false, and openWorldHint=true, so the safety profile is covered. The description adds a genuinely important non-schema behavior: the full key is only shown once upon creation, which tells the agent how to handle and relay the result.

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, front-loaded with the action and resource, then the critical one-time-display caveat. Nothing is wasted.

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

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

For a single-parameter creation tool with annotations covering safety traits and no output schema, the description is nearly complete: it identifies the account scope and the one-time key disclosure. Minor gaps (scopes/permissions on the new key, whether names must be unique) keep it short of a 5.

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

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

There is a single parameter with 100% schema description coverage that already includes examples ('Claude Desktop', 'CI/CD'). The description adds no 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 ('Create') and resource ('API key') scoped to the Xyle account, which cleanly separates it from siblings like list_api_keys and revoke_api_key. It doesn't explicitly name an alternative, but the operation is unambiguous.

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

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

No when-to-use guidance, no prerequisites, and no mention of sibling alternatives such as revoke_api_key or list_api_keys. The agent must infer the trigger context entirely.

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

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

Annotations declare destructiveHint=true, readOnlyHint=false, openWorldHint=true, idempotentHint=false. The description does not disclose any of this behavioral profile: it doesn't say whether creating an audit overwrites or replaces an existing audit, what side effects occur (crawl, external API calls, etc.), or whether the operation can be re-run idempotently. With no annotations-carried warnings amplified and no destructive/idempotency context added, transparency is weak. No contradiction with annotations, so not a 1.

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

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

Two sentences, front-loaded with the core action and then a concrete prerequisite step. No filler, though the second sentence's reference is somewhat terse and could be slightly more explicit about ordering.

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, non-idempotent, open-world creation tool with no output schema, the description should do more: describe what the output is (a report? an audit ID?), whether it can be re-run, and how it relates to the many sibling audit/report tools. As written it leaves the agent without critical behavioral context.

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

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

The input schema has 100% description coverage for both required parameters (domain, client_name), so the schema already documents them fully. The description adds no parameter-specific detail beyond naming the site being audited, which is baseline behavior when the schema does the heavy lifting.

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 ('Create a comprehensive SEO audit for a site') and enumerates the analysis areas (technical SEO, content, performance, prioritized actions). It's clear what it does, though it doesn't directly distinguish itself from close siblings like get_audit, list_audits, or audit_chat, so it's one notch below 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?

It gives an important sequencing hint – call get_audit_framework(section=report_template) before writing the polished report – which is concrete guidance about prerequisite steps. However, it doesn't clarify when this tool should be used versus the many sibling audit tools (get_audit, get_audit_report, gbp_audit, start_prospect_audit), so usage guidance is only partially covered.

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 covering write/open-world/destructive profile, the description adds substantial context beyond them: the exact evidence collected, the <3-rivals trigger for a live Google fetch, its ~$0.0155 cost, and what lands in evidence.serp. The dedupe rule (existing brief returned) is exactly the kind of behavior an agent cannot infer from 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?

Long but front-loaded: the purpose and keyword scope come first, then evidence, then the live-SERP fallback, then the return and dedupe rule. Dense enumerations of evidence fields are justified for a tool this complex, though the list of artifacts is close to exhaustive.

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 9-parameter, no-output-schema mutation tool, the definition covers what is created, what side effects occur (SERP fetch, cost), and what the response contains ('brief with evidence and a next_step'). Minor gap: it doesn't describe the brief's own structure or what next_step values imply.

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 real meaning beyond the schema strings: it explains the opportunity object's passthrough semantics ('kept verbatim', reasoning preserved), the live_serp trigger condition, and names the specific derived target fields. It stops short of clarifying kind/intent interaction or the notes field.

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 ('Open a brief for one keyword') and immediately spells out the evidence bundle it assembles. An agent can distinguish it from get_content_brief, list_content_briefs, update_content_brief and publish_content_brief without opening a schema.

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

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

Gives concrete routing guidance: pass the opportunity object from content_opportunities, and the 'one open brief per keyword per site — an existing one is returned instead' rule tells the agent this is safe to call repeatedly. It doesn't explicitly say when to prefer get_content_brief or when a brief should be updated rather than opened, so it stops short of full when/when-not coverage.

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, idempotentHint=false) by disclosing that the baseline is measured server-side at creation and must not be passed or invented. It also explains the downstream progress-tracking behavior of each of the three measurement modes, which is critical context an agent cannot infer from schema or annotations.

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

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

Front-loaded with the core rule and hierarchy, then examples. It is longer than average but nearly every sentence carries a decision the agent must make. The parenthetical about citation rate scoring is slightly verbose relative to its value.

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

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

For a 14-parameter mutation tool with no output schema and open-world behavior, the description covers the novel, non-obvious mechanics thoroughly (server-side baseline, three measurement modes). Some ancillary parameters and any post-creation behavior beyond progress tracking are left to the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description still adds substantial meaning: it explains the interaction between metric_key, manual_total, and the fallback to link_goal_issues, and the ai_citation_rate example clarifies target_value semantics. It does not, however, clarify several of the 14 parameters (tags, stage, priority, due_at).

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 the specific verb+resource (create a goal for a brand) and immediately constrains the hierarchy to exactly two levels (top-level or sub-goal via parent_id). It clearly distinguishes itself from siblings like update_goal, delete_goal, list_goals, and content_for_goal.

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 three worked examples function as explicit when-to-use guidance: use metric_key when a metric covers it, manual_total when no metric covers it, and neither when progress should track linked issues. It ends by telling the agent to pick whichever reflects the work, with the failure mode spelled out.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, openWorldHint=true, and idempotentHint=false, so the safety profile is covered. The description adds nothing behavioral — it doesn't warn that each call creates a separate persistent session (non-idempotent) or that this may consume quota/credits, which would be useful 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?

Two sentences, front-loaded with the action; the second sentence usefully previews outputs since there is no output schema. The 'provide a seed topic or URL' clause slightly overlaps the schema but is not 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?

With no output schema, the description correctly summarizes what the session yields (related keywords, volumes, clustering), and a required description of mutation semantics is partly carried by the destructive annotation. It could better note that sessions persist and are individually addressable (get_keyword_session/list_keyword_sessions), but it is adequate for a 4-parameter creation 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 topic, country, site_id, and language are all documented in the schema. The description only mentions a seed topic or URL, adding no syntax, defaults, or format details beyond what the schema provides. 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 (start a keyword research session) and names the outputs (related keywords, search volumes, clustering). It does not explicitly distinguish itself from siblings like keyword_chat, get_keyword_session, or seed_keywords_from_gsc, but the core purpose is unambiguous.

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

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

The description says what seed input to provide but gives no when-to-use guidance, no prerequisites, and no mention of alternatives such as keyword_chat or list_keyword_sessions. The agent must infer context from the name alone.

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=false, and openWorldHint=true, which is a lot of behavioral signal. The description adds nothing beyond that — no mention of the surprising destructive flag on a create operation, no cost/credit implications, and no note about what happens if the domain is already registered.

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

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

One short sentence, front-loaded with the action and resource, with zero wasted words. Nothing to trim.

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

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

For a one-parameter create tool with rich annotations and full schema coverage, the description is minimally sufficient. It still leaves open the behavior on duplicate domains and the practical meaning of the destructive flag, which are the details an agent would most want before invoking it.

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

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

Schema description coverage is 100% and the single 'domain' parameter is fully documented with an example format in the schema. The description contributes no additional parameter meaning, 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 ('Add a new website') plus the account scope and intended domain of use (SEO tracking and analysis). It does not, however, differentiate itself from adjacent siblings such as delete_site, list_sites, or get_site, so the reader must infer the distinction from the name alone.

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 guidance, no prerequisites, and no mention of alternatives. Nothing tells the agent what conditions should trigger creating a site versus adopting one via adopt_site_redirect or connecting an existing property like connect_ga or connect_wordpress.

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 (readOnly, openWorld, non-idempotent) by disclosing what gets recorded (14 named features plus function-word rates with the author's own range), what persists downstream (every brief carries evidence.voice), and an important non-behavior guardrail ('This is never an AI-detection score'). This is rich, non-obvious context that annotations cannot 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?

Purpose is front-loaded and the sentences are dense with useful specifics rather than filler. It is on the long side and could be trimmed slightly, but nearly every clause carries actionable 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 tool with no output schema, it explains the downstream payoff (distance metrics reported by review_writing/score_content_draft) and the input requirements thoroughly. The only modest gap is that it does not describe what create_voice_profile itself returns on the call.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantive meaning: URL count guidance (6-10, vs the schema's max 25), word-count thresholds, preference for unedited drafts, and the rule to keep one profile per register. This meaningfully augments the schema rather than restating it.

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 — building a 'VOICE FINGERPRINT' from the author's own unedited writing — and names the downstream artifacts (evidence.voice, review_writing, score_content_draft). An agent can distinguish it from siblings like declare_voice, get_voice_profile, and voice_probe 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 concrete input guidance (6-10 URLs, 5,000+ words recommended, 2,000 minimum, unedited drafts beat published posts) and an explicit behavioral instruction: 'Ask the user for the samples; do not pick them yourself.' It does not explicitly name alternative sibling tools or state when-not to use it, so it falls short of a 5.

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

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

Annotations cover the safety envelope (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the bar is lower, but the description adds real lifecycle context beyond them: the declared constraints are labelled 'declared' and are superseded automatically when a measured profile builds. It also instructs 'Ask them in one message; skip any the author does not care about', which is behavioral guidance not present in the schema.

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

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

Front-loaded with the when-to-use condition, then the mechanics, then the question list. Information-dense with no filler, though the parenthetical about the 2,000-word threshold and the trailing instruction make it longer than strictly needed.

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

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

No output schema exists, but the description explains what is produced and how it is later replaced, so the agent understands the state change. The only gap is the return value/confirmation shape, which is minor for a small two-parameter write.

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 would be 3, but the description enumerates the six answer keys and their allowed values (contractions yes/no; person i/we/neither; dashes dashes/commas; formality casual/plain/formal; sentences short/mixed/long), which the free-text 'answers' JSON schema does not constrain. That is meaningful added semantics for a schema with zero enums.

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 ('ask the author six quick questions and save the answers as DECLARED voice constraints') and names the exact artifact produced. It also distinguishes itself from the measured-profile path by spelling out coexistence ('used and labelled declared until the measured profile builds itself'), so an agent can tell it apart from create_voice_profile and get_voice_profile.

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?

Opens with the selecting condition 'No writing samples yet?' and adds a concrete trigger point (automatic once 2,000 words are on file), which tells the agent when this tool is the right one. It stops short of naming sibling alternatives (voice_probe, create_voice_profile) explicitly.

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 and idempotentHint=true, so the safety profile is covered; the description goes further by disclosing cascade behavior that annotations cannot express — sub-goals survive as top-level goals and linked fix-queue issues are unlinked rather than deleted. That is exactly the kind of non-obvious side-effect an agent needs before calling a destructive 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?

Front-loads the core action and cascade semantics in the first sentence, then the usage rationale. The final clause is somewhat wordy ('there is no separate archive state, this is the only cleanup path') but each sentence carries distinct, useful 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 two-parameter destructive delete with no output schema and full annotation coverage, the description supplies everything an agent needs: purpose, confirmation of permanence, cascade effects, and the alternative cleanup context. No meaningful 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%, with both goal_id and site_id documented ('Goal id from list_goals', 'The brand/site ID'). The description adds no additional parameter meaning, 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 ('Permanently delete a goal') and immediately clarifies scope with the 'Permanently' qualifier, distinguishing it from update_goal and list_goals. An agent knows exactly what operation this performs without consulting siblings.

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

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

Explicitly says when to use it ('to clean up a duplicate or superseded goal') and contrasts with the alternative ('instead of leaving it around marked do not use'), plus notes there is no archive state and this is the only cleanup path. Nothing about selection is left to inference.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds nothing beyond that – it does not say whether the deletion is permanent, what happens to derived data (keywords, rankings), or whether it requires ownership/permissions.

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

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

One short sentence with the action front-loaded and zero filler. It is appropriately sized for a trivial single-parameter delete, though it is arguably too sparse to be a model of conciseness-with-substance.

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

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

The tool is simple, annotations cover the destructive/idempotent profile, and the schema documents the only parameter, so the core is not missing. Still, for a destructive operation the description could note permanence or affected related data, leaving a modest gap.

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

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

There is a single parameter and schema description coverage is 100%, so the schema already documents session_id fully. The description adds no format, source, or retrieval guidance beyond the schema, giving the baseline 3 for a fully-covered parameter.

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

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

States a specific verb ('Delete') and resource ('keyword research session'), so the agent knows exactly what the tool does. However it offers no differentiation from sibling deletions like delete_goal, delete_site, or delete_wordpress_site.

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 guidance on when to use this versus get_keyword_session/list_keyword_sessions or create_keyword_session. No prerequisites, no warning about irreversibility, and no indication of the selection condition that should trigger this 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?

Annotations already declare destructiveHint=true, idempotentHint=true, openWorldHint=true, and readOnlyHint=false. The description adds valuable scope context by specifying that the removal is only from the Xyle account and explicitly does not delete external data, which helps the agent understand what is actually destroyed.

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 zero waste. The core action is front-loaded, and the scope caveat follows immediately.

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 low complexity, a fully documented single parameter, and rich annotations covering the safety profile, the description is nearly complete. It could be improved by explicitly distinguishing this from related tools like delete_wordpress_site, but it covers what the agent needs for a correct basic invocation.

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

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

The schema fully documents the single required parameter site_id, including its description. The description does not add any syntax, format, or constraint details beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description states a specific verb ('Remove') and resource ('a website from your Xyle account'), making the core purpose clear. However, it does not explicitly differentiate this tool from siblings such as delete_wordpress_site or create_site.

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

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

The description gives no when-to-use guidance, no prerequisites, and no alternatives. The statement 'This does not delete any external data' is a scope clarification rather than usage guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful scoping: what is removed is the connection plus the stored key reference, not the WordPress site's content — an important distinction given the tool name says 'delete site'. It omits reversibility and the behavior on a second call despite 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?

A single sentence with zero filler, front-loading the primary action (disconnect) before the secondary effect (key reference deletion). Nothing is padded or repeated.

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

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

For a one-parameter teardown tool with rich annotations and no output schema, the description covers the essential question of what is destroyed. Minor gaps remain around idempotency/reversibility and how to re-establish the connection, but nothing critical is missing.

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

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

Only one parameter (site_id) and schema description coverage is 100%, so the schema fully documents it. The description adds no format hints or meaning beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb pair and resource: 'Disconnect a WordPress site from Xyle and delete its stored key reference.' This clearly sets it apart from connect_wordpress, verify_wordpress, set_wordpress_connection, and get_wordpress_site. It does not explicitly name a sibling, but the action is distinctive enough that an agent can place it.

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 indication of when to use this versus alternatives (revoke_api_key, set_wordpress_connection, or simply leaving the connection in place), and no prerequisites or exclusions. The agent must infer that this is the teardown counterpart of connect_wordpress.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the 'works for any page type' scope and a usage hint, but does not explain the non-idempotent behavior (idempotentHint=false) or what the returned recommendation looks like. Moderate added value over 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?

Two tight sentences, front-loaded with the core purpose and output list, followed by the practical usage hint. No filler or redundancy.

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

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

For a read-only, all-optional-parameter tool with no output schema, the description adequately conveys what the tool produces by enumerating the design system components. It could say more about the return structure, but the enumerated outputs largely cover that need.

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 four optional parameters with examples. The description only adds a hint about populating 'keywords' from a snapshot, which is marginal over the schema's own example ('minimal, trust, dark, bold — include what you saw in a snapshot'). Baseline 3 applies.

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

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

The description uses a specific verb ('Recommend') plus resource ('complete design system') and enumerates the concrete outputs (palette, style, font pairing, sections, UX rules, anti-patterns), which clearly separates it from the sibling design_search. It stops short of explicitly naming a sibling alternative, so it falls just below 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?

It gives clear operating context ('Works for ANY page type') and a concrete recommended workflow ('first get a SNAPSHOT from the user and pass what you observed as keywords'). It does not state when NOT to use it or name an alternative tool, so it lacks exclusions.

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, destructiveHint=false and openWorldHint=true, covering the safety profile. The description adds 'Returns ranked matches', a useful output hint, but says nothing about why idempotentHint=false (result variability) or how ranking works.

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

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

Two tight sentences with the scope constraint front-loaded and the return behavior appended; every clause carries information and there is no filler.

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

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

For a two-parameter, no-output-schema search tool, the description covers what it searches, the constrained domain set, and that results are ranked. The only real gap is matching behavior for the optional query parameter.

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 query and domain. The description restates the domain enum but adds no matching semantics, query syntax, or default behavior beyond what the schema provides.

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

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

States a specific verb (Search) and resource (design knowledge base) and enumerates the domain scope, which distinguishes it from neighbors like design_recommend and assist_design_lint. It stops short of naming those siblings explicitly, so it doesn't reach 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?

The phrase 'in one domain' implies the single-domain constraint and that a domain must be chosen, but there is no explicit when-to-use guidance and no mention of when design_recommend or assist_design_lint would be preferred 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?

Goes well past the annotations, which only declare readOnly/openWorld/idempotent flags. The description discloses output-quality behavior that no structured field carries: that low-keyword sites surface LinkedIn/Reddit/Substack/Wikipedia as false positives, and that avg_position is the discriminator (4th = competitor, 14th = publisher). This is exactly the kind of operational context an agent cannot 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?

Front-loaded with the purpose, then the caveat, then the remedy — a good information hierarchy. It is dense and every sentence carries weight, though the docs/competitor-analysis-runbook.md pointer is a reference the agent may not be able to resolve, and the caps-lock warning is slightly heavy for the length.

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

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

No output schema exists, so the description must carry return semantics, and it largely does: overlapping keyword domains, a counted overlap, an avg_position signal, and a post-filter candidate count. It stops short of describing the full row shape (what other columns come back), which is the only real remaining gap for an agent consuming the result.

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

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

Schema description coverage is 100%, so the schema already documents domain, limit (post-filter count, default 10), and location_code with example codes. The description only adds a light gloss ('yours or a prospect's') and no format or syntax detail beyond the schema, so the baseline 3 for fully-covered parameters applies.

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

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

States a specific verb+resource with scope: 'Organic competitors for ANY domain (yours or a prospect's) in one call — domains ranking for the same keywords, with the overlap counted.' That is precise enough that an agent can distinguish it from sibling landscape tools like get_competitive_landscape or get_competitor_keyword_overlap 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?

Explicitly frames the output as a candidate list rather than an answer, warns that platform domains co-rank by accident on thin sites, and prescribes a next step ('Shortlist 4-6 real companies by hand, then call domain_keyword_profile on each'). What it does not do is route against the sibling competitor tools (get_competitive_landscape, list_competitors, get_competitor_keyword_overlap), so alternative selection is left to inference.

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

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

Annotations already cover safety and world assumptions, but the description adds material context they cannot: per-call cost (~$0.05), that it is one request regardless of domain, that the data comes from a proprietary Google index which lags a live SERP, and that results are not device-specific. It even frames the disclosure obligation when publishing the numbers.

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

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

Three sentences, front-loaded with the core payoff (keywords plus volume and position, one request, any domain). Every sentence carries information, though the capitalised 'ONE' and the cost/pitch framing are slightly promotional for a tool definition.

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

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

With no output schema, the description does indicate the return shape at a high level (keywords with search volume and position) and covers cost, source, and freshness caveats. It stops short of describing output structure or size limits in detail, but nothing critical for a correct call is missing.

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

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

Schema description coverage is 100%, so the schema already documents domain, limit (with the 200-500 guidance and 'still one request'), and location codes. The description reinforces the one-request-per-call economics but adds no parameter syntax beyond what the schema provides, 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: every keyword a domain ranks for, with search volume and position. It also scopes the tool apart from siblings by noting it works for any domain including competitors you do not own, so an agent can distinguish it from ownership-bound tools like get_gsc_queries or competitor-overlap 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?

Gives a concrete when-to-use context (onboarding or pilot reports, run for client plus shortlisted competitors, then diff), which is strong situational guidance. It does not name alternative sibling tools or state exclusions, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds behavioral value beyond that: it will never trigger a new paid fetch (cost behavior) and returns 404 under a specific pre-condition (error behavior), neither of which is in the annotations. It does not explain the idempotentHint=false flag, which is a minor gap.

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 tightly packed sentences, front-loaded with the action and scope before the caveats. Every clause earns its place (threshold behavior, cost guarantee, 404 dependency); no filler.

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

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

For a one-parameter, no-output-schema tool whose annotations cover safety, the description supplies the key operational facts an agent needs: caching behavior, cost guarantee, and the 404 prerequisite. What the returned file looks like is not described, but that is minor for this tool.

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

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

Single parameter site_id with 100% schema description coverage, so the schema carries the parameter burden. The description adds no syntax, format, or sourcing detail for site_id beyond what the schema states. 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?

Specific verb (generate/download) plus resource (Google Search Console disavow file) and scope (from the site's cached backlink profile, filtered by toxicity threshold). It explicitly names the sibling get_backlink_profile as the prerequisite, so an agent can distinguish it from that tool without opening either schema.

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

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

Gives a clear invocation condition and prerequisite: 'Returns 404 if the backlink profile hasn't been fetched yet (call get_backlink_profile first).' This routes the agent correctly. It doesn't state a negative case or an alternative tool for the refresh path, but the context is unambiguous.

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, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds that the output is downloadable PDF content, which is useful but does not detail authentication needs, rate limits, or error behavior. With annotations doing the heavy lifting, this is adequate but not rich.

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

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

The description is a single, front-loaded sentence with no wasted words. It immediately conveys the action and the return type.

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 two required parameters and no output schema, the description states the output format (PDF content) but does not explain how the content is delivered (e.g., binary stream vs. URL) or any error conditions. Combined with existing annotations and schema, it is minimally sufficient but leaves some gaps for a download 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%, but the schema descriptions are minimal ('The site ID', 'The report ID'). The description adds no further parameter meaning beyond what the schema provides. Per the rubric, high schema coverage yields a baseline of 3 even without additional param info 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?

The description uses a specific verb (Get) and resource (report), and clarifies the output is 'downloadable PDF content', which distinguishes it from a generic report fetch. However, it does not explicitly name or contrast with sibling tools like get_report or generate_report.

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

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

The description provides no guidance on when to use this tool versus alternatives such as get_report or export_audit_report. It merely states what the tool does, leaving the agent to infer appropriate usage contexts.

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, destructiveHint=false, openWorldHint=true and idempotentHint=false, covering the safety profile. The description adds that results are categories plus topic titles (a structural/map behavior), but says nothing about pagination or result size caps beyond what the schema's 'detail' param implies.

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

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

One tight sentence with no filler; the core purpose is front-loaded and the secondary usage framing is appended after a dash. Every clause carries 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?

No output schema exists, so the description usefully conveys the shape of the return (categories with topic titles) and one optional param handled by the schema. It is nearly complete for a trivial read-only listing tool, though it could note that it is Elementor-specific navigation rather than a content search.

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 'detail' parameter (concise=5 topics vs detailed=all topics) is already fully documented in the schema. The description mentions 'topic titles' but adds no syntax, defaults, or format detail beyond that. Baseline 3 for high schema coverage.

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

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

States a specific verb ('List') and resource ('Elementor knowledge categories with their topic titles'), which is concrete enough for an agent to distinguish it as a discovery/listing tool. It does not directly name siblings like elementor_search or elementor_get, so differentiation is inferential rather than explicit.

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

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

'the map/router for browsing what's available before searching' gives clear usage context: call this first, in a reconnaissance role, ahead of a search. It stops short of explicitly naming elementor_search as the follow-up alternative or stating when-not to use this 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?

Annotations already cover safety (readOnlyHint=true, destructiveHint=false, openWorldHint=true). The description adds real value beyond them by disclosing the return payload: a distilled guide, a real PHP/JS snippet, the source docs URL, and related entry ids. This matters because there is no output schema. It does not explain the unusual idempotentHint=false, but that is minor.

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

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

One sentence, front-loaded with the action and resource, with the parenthetical source and the return-content list earning their place. Zero filler.

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

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

With no output schema, the description carries the return-value burden and does so concretely (guide, code snippet, docs URL, related ids). Combined with the 100%-covered single parameter and read-only annotations, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100% and the schema already documents the id format with two examples, so baseline 3 applies. The description goes slightly beyond by naming the provenance of the id (elementor_search results), which helps the agent supply a valid value.

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 (Fetch) + resource (one Elementor knowledge entry) + cardinality (one), and it explicitly ties itself to the sibling elementor_search as the source of ids. An agent can distinguish elementor_get from elementor_search/elementor_categories without opening 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?

States the precondition clearly: the id comes 'from elementor_search results', which tells the agent this follows a search. It doesn't spell out a when-not case (e.g. use elementor_search when you don't have an id yet), but the workflow is unambiguous.

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