BlogSEO

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

The description goes far beyond the annotations by disclosing that duplicate keywords are skipped, clustering and intent classification run asynchronously, and the credit is charged even if all keywords were already tracked. It also states the rate limit, credit cost, non-refundability, and subscription requirement. This gives the agent a strong understanding of real-world behavior and side effects.

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

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

The description is dense but every sentence provides necessary operational detail: what the tool does, what it skips, background processing, rate limits, credit costs, auth requirements, and alternative routing. Despite its length, it is well-organized and front-loads the core behavior before secondary caveats.

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

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

The description covers prerequisites, quota limits, cost implications, failure behavior, asynchronous effects, parameter requirements, and sibling tool differentiation. Together with the output schema, an agent has everything needed to invoke the tool correctly and anticipate outcomes.

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?

While the schema already documents all parameters, the description adds critical semantics: confirm=true acknowledges the credit charge, omitting it returns only the cost and balance, and website_id is needed only for multi-website accounts. The exact keyword count range and the 'exactly as written' behavior add meaning beyond the schema's field names and types.

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

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

The description clearly states the tool adds given keywords to the keyword plan exactly as written, with volume, difficulty, and CPC from the provider. It differentiates itself from research_keywords by explicitly noting that nothing is expanded or invented and that research_keywords is for discovering related ideas. This makes the tool's purpose unambiguous.

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

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

The description gives explicit when-to-use guidance, including the alternative research_keywords for discovery use cases. It also details limits shared with research_keywords, the confirm=true requirement, and the website_id field conditions. The agent knows exactly when to call this tool versus others.

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 state readOnlyHint=false and destructiveHint=true, but the description goes far beyond that: it discloses asynchronous execution, skipping of still-generating articles, the Out of Sync side effect on published articles, charging/refund behavior on provider failure, and subscription requirements. These are substantial behavioral disclosures that the annotations alone would not convey.

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

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

The description is a dense 8-sentence paragraph, but every sentence adds distinct information—async behavior, skip/charge rules, Out of Sync effect, alternative tool, costs, confirm requirement, and website_id. It front-loads the core action and limitation. Slightly long for the information, but well-ordered and free of fluff.

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

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

For a complex async batch tool with cost and side effects, the description covers all critical operational context: what happens, when, what to check, what to acknowledge, what prerequisites exist, and how to route to alternatives. The presence of an output schema means return values need no explanation. No important gap is evident.

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

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

Schema description coverage is 100%, so baseline is 3. The description paraphrases the schema's parameter descriptions (confirm, website_id, article_ids, instructions) without adding new meaning. The extra context about credit charging and skipping is behavioral rather than parameter-specific, so there is no significant added semantic value 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?

The description opens with a specific verb-resource pair: 'Queues an AI rewrite of up to 50 articles with the same instructions.' It also differentiates from the sibling tool edit_article_with_ai by explicitly pointing to it for single-article or translation use, so an agent can immediately distinguish batch vs. single editing.

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 explicit when-to-use and when-not-to-use guidance: 'Use edit_article_with_ai for a single article or a translation.' It also covers prerequisites (active subscription/free trial), the confirm flag requirement, the website_id condition, and async behavior with a pointer to check results via get_article. Nothing 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?

Beyond the read-only/idempotent/non-destructive annotations, the description discloses that nothing is modified, that checks are skipped when no base URL is set, and that translations get no benchmark or cannibalization checks. It also states the result shape (statuses good/ok/bad/na, semantic coverage, prioritized fixes), adding real behavioral context.

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

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

The description is dense but every sentence earns its place: scope, check categories, conditional advanced analysis, locale behavior, return format, base-URL exception, and website_id guidance. It front-loads the core computation and maintains a logical flow from normal behavior to exceptions.

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 three-parameter tool with an output schema, the description covers all relevant edge cases: translation scoring, multi-website accounts, absence of advanced analysis, missing base URL, and the free/non-destructive nature. Nothing essential for an agent to invoke 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?

Although the schema already covers all three parameters, the description adds decisive semantics: locale means scoring a translation against its localized keyword with benchmark and cannibalization disabled, article_id refers to saved article content, and website_id is needed only when an account has multiple websites. This goes beyond the schema's lexical descriptions.

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

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

The description opens with a specific verb+resource: it computes the on-page SEO score of an article from saved content, including a concrete 0-100/S+ to D grading scale. It further separates itself from the run_advanced_seo_check sibling by explaining when that analysis affects this tool's benchmark output, so an agent can tell it apart.

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

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

The description gives concrete calling context: pass locale to score a translation instead of the default article, pass website_id only for multi-website accounts, and expect a competitor benchmark only when advanced analysis exists. It does not explicitly list exclusionary criteria versus check_seo_score or other siblings, but the conditions are clear enough for correct selection.

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

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

Beyond the annotations, the description discloses meaningful behavioral details: calls are charged even when cached, results are cached for 7 days, cache misses can take up to two and a half minutes, there is a 30-per-hour limit, and the credit is refunded if the provider fails. No contradiction with annotations exists; the readOnlyHint=false aligns with the described non-free, non-idempotent behavior.

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

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

The description is long but densely informative, with each clause covering a distinct operational concern: output contents, normalization, caching, cost, latency, rate limits, and authentication. It is front-loaded with the primary purpose and the most relevant selection-relevant facts, though the output field enumeration could arguably be trimmed.

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

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

Given the tool's complexity, the description covers all necessary context: input normalization, caching behavior, costs, failure refund, rate limits, subscription requirements, website_id handling, and the key alternative tool. An output schema is already present, so detailing return values is unnecessary.

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 both parameters. The description adds important semantic clarity by explaining that subdomains and paths are reduced to the registrable domain, and by specifying when website_id is needed, which goes beyond the schema's basic descriptions.

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

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

The description states a specific verb and resource: 'Returns the backlink profile of any domain' from the DataForSEO backlinks index, enumerating the exact metrics returned. It explicitly distinguishes itself from the sibling check_domain_rating by naming when that alternative is appropriate.

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

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

The description clearly says to use check_domain_rating when only Domain Rating is needed, and explicitly warns not to call check_backlinks twice for the same domain due to credit charges and caching. It also provides rate limits, caching duration, and required subscription context, giving the agent actionable selection criteria.

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 readOnly/openWorld/idempotent annotations, the description discloses important behavioral details: normalization to registrable domain, 24-hour caching, and a 60-lookups-per-hour rate limit. These details help the agent predict repeated-call behavior and throttling without contradicting annotations.

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

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

The description is concise and front-loaded: the main purpose appears first, followed by scope, input behavior, caching, and rate limit. Every sentence carries useful information and there is no redundancy or 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 single-parameter read-only tool with an output schema and strong annotations, the description is complete. It covers what the tool returns, which domains are in scope, how input is normalized, cache behavior, and rate limits. Nothing essential is missing for an agent to invoke it correctly.

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

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

The input schema already describes domain_or_url as a domain name or full URL, and schema coverage is 100%. The description adds meaningful semantic depth by explaining that subdomains and paths are reduced to the registrable domain, with a concrete example, which goes beyond the schema's basic 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 states a specific action and resource: returns Ahrefs Domain Rating (0-100 authority score) for any domain. It clearly differentiates the tool from siblings by emphasizing it works for competitors, prospects, and sites found in backlinks, not just the user's own websites.

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 clear usage context: it is for checking authority of any domain, including competitors and link-building prospects. It does not explicitly name alternative tools or state when not to use it, but the context is strong enough that an agent can infer appropriate scenarios.

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 provide readOnly/idempotent/openWorld hints, but the description adds substantial behavioral context beyond them: server-side fetching as Googlebot with Chrome fallback, no JavaScript execution, 1 MB HTML cap, 1-hour cache, failure modes, and rate limiting. This gives the agent a realistic model of how the tool behaves before calling it.

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

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

Six sentences, each dense with non-redundant information, starting with the core output and progressing through fetch details, failure handling, scope, and limits. There is no filler or repetition; the structure makes it easy for an agent to quickly extract constraints.

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

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

The description covers input modes, computed outputs, fetch mechanism, success/failure conditions, scope, cache behavior, and rate limits. Since an output schema exists, return-value details do not need to be repeated, and nothing critical is missing for an agent to decide when and how to invoke this tool correctly.

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

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

Schema coverage is 100% and each parameter already has a solid description, so the baseline is 3. The description adds meaning beyond the schema by explaining target_keyword's verdict threshold (0.5%–2.5%), placement flags behavior, and the url/text mutual-exclusion rule. This is valuable clarification, though not exhaustive since schema already covers defaults and ranges.

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?

Description states a specific verb and resource: 'Computes keyword density for a public page URL or a block of text' and enumerates exact outputs (word counts, reading time, n-grams, target keyword verdict). This clearly differentiates it from siblings like check_seo_score or research_keywords, which target broader SEO analysis.

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?

Description gives explicit usage context: exactly one of url or text must be provided, and it tells the agent to pass page text when the URL fails due to bot protection, non-HTML, or JavaScript-only pages. It also clarifies any public page can be checked and notes the 20-per-15-minute rate limit. It does not explicitly compare against sibling tools, but the within-tool guidance is strong.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context: the keyword-in-slug check always reads as a reminder for pasted content, the tool is free and instant, and the conditional behavior when target_keyword or site_url are omitted. It doesn't describe rate limits or exact response format, but the output schema exists and the description summarizes the return structure.

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

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

The description is dense but well-organized, front-loading the core purpose and then covering return values, use cases, conditional behavior, and sibling routing. It's a long paragraph but every sentence adds information. Slightly long, but justified given the tool's complexity and 7 parameters.

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

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

The description is complete for a read-only scoring tool. It covers what checks are performed, what the return value includes, when to use it vs alternatives, conditional parameter behavior, and the website_id prerequisite. The output schema exists, so return values are further documented. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all 7 parameters. The description adds some context beyond the schema: it explains the consequence of omitting target_keyword and site_url, and mentions website_id comes from get_account. However, it doesn't add much detail about the parameters themselves beyond what the schema provides, so a baseline 3 is appropriate.

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

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

The description clearly states the tool scores inline content with the same on-page SEO checks as BlogSEO articles, listing the specific checks performed. It distinguishes itself from siblings like check_article_seo_score (which likely scores articles stored in BlogSEO) by explicitly saying 'use get_article for articles stored in BlogSEO' and noting the content does not need to be in BlogSEO.

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

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

The description explicitly states when to use this tool ('use it on drafts, pages from other tools or competitor copy') and when not to ('use get_article for articles stored in BlogSEO'). It also provides conditional guidance: 'Without target_keyword the keyword checks are skipped; without site_url the link checks are not applicable' and 'Pass website_id when the account has several websites (see get_account).'

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

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

The description richly discloses side effects beyond the sparse annotations: it turns on auto-publish, sends every published article as JSON, returns a shared secret exactly once for auth_method=generated, and establishes a one-webhook-per-organization constraint. It also notes compatibility with CMS integrations and that certain builder connections count as webhooks. This gives an agent a strong model of what will happen.

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

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

The description is dense but every sentence earns its place: prerequisites, delivery behavior, authentication handling, constraints, next step, and cost. It is front-loaded with the core action and effect. It could be slightly improved with bullet-style separation, but it remains focused and free of 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 tool with 7 parameters, side effects, authentication nuances, and cross-tool dependencies, the description covers the critical operational context: setup requirements, secret handling, one-per-organization limitation, coexistence with CMS integrations, and follow-up verification via test_custom_webhook. An output schema exists, so explaining return values is unnecessary. Nothing essential is missing for an agent to call this 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?

The input schema already documents all 7 parameters with descriptions and enums, so the baseline is 3. The description adds meaningful behavioral context for key parameters: auth_method=generated means the secret is returned exactly once and must be stored in environment variables, platform has the special meaning that several builder connections are webhooks, and website_id should be passed for multi-website accounts. This exceeds schema-only understanding.

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

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

The description opens with a specific verb and resource ('Connects a custom webhook') and immediately clarifies the behavioral consequence: BlogSEO POSTs every published article as JSON to the endpoint. It also distinguishes this tool from related siblings by referencing get_webhook_contract and test_custom_webhook, making its role 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?

The description gives clear operational guidance: the endpoint must already be deployed and reachable over HTTPS, one webhook is allowed per organization, and test_custom_webhook should be called afterwards. It also explains when website_id is needed. It does not explicitly state when to prefer alternatives over this tool, but it provides enough context to infer appropriate use.

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

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

The description goes well beyond the annotations by disclosing that the conversion is irreversible, that credits are charged before the work, and that charges are not refunded on failure. These are important behavioral facts not derivable from destructiveHint alone.

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

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

The description is dense but every sentence earns its place, covering rate, irreversibility, cost rule, subscription requirement, confirmation behavior, and website_id handling. It is front-loaded with the core conversion fact and then layers necessary operational details.

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

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

The description covers all essential operational dimensions: cost, irreversibility, failure refunds, authentication requirements, confirmation flow, and parameter conditions. With an output schema present, the return value details are adequately handled elsewhere.

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?

Although the schema already covers all parameters, the description adds meaning: amount is defined as AI brain credits spent with a 1-to-100 range, confirm is tied to acknowledging the charge, and website_id is tied to multi-website accounts and the get_account source. This is strong value beyond the schema.

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

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

The description names the exact verb and resource: it converts AI brain credits into backlink credits. It also specifies the fixed conversion rate and the intended purpose, which clearly distinguishes it from any sibling tool.

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

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

The description provides explicit when-to-use and how-to-use guidance: it states the subscription/free-trial requirement, explains the confirm=true prerequisite for actually performing the conversion, and gives the website_id condition for multi-website accounts. This leaves 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?

Annotations only declare the generic write/open-world profile; the description adds the operationally critical behavior that nothing is live until DNS points at the target, that a CNAME record is returned, that articles publish automatically once connected, and that the feature is free. It also discloses the side-effect semantics an agent needs before calling.

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 action is front-loaded and every clause carries functional information (constraints, return value, follow-up tool, cost). It is delivered as one dense run-on paragraph rather than being chunked, which slightly hurts scannability but nothing is wasted.

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

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

For a two-parameter mutation with an output schema, the description covers everything an agent needs: constraints, prerequisite-free call, DNS dependency, follow-up status check, and multi-website disambiguation. Return-value detail is rightly left to the 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 description coverage is 100%, and the schema already documents the hostname default (blog.<website domain>) and the website_id behavior including the get_account reference. The description mostly restates that guidance, adding no new syntax or format details, 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 (creates) and a precisely defined resource (a hosted blog served by BlogSEO on a subdomain, with sitemap/RSS/OG/structured data). It is unmistakably distinct from siblings like get_hosted_blog_status or sync_article_to_cms, and even explains the mechanism (HTTPS subdomain hosting).

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 preconditions and exclusions: subdomains only, one hosted blog per organization, not alongside a CMS integration like WordPress or Shopify, and pass website_id when the account has multiple websites (routing to get_account). It also names the required follow-up tool, get_hosted_blog_status, after the call.

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

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

Annotations are sparse and only indicate readOnly/idempotent/destructive hints, so the description carries the behavioral burden. It discloses the upload_url expiry, deletion policy, unused-upload quota, file size limit, supported formats, and cost, which is rich and useful behavior beyond what annotations provide.

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

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

The description is compact yet information-dense, with the primary purpose and sibling relationship front-loaded before operational details. Every sentence adds a distinct piece of information: purpose, return values, format/size, expiry/lifecycle, quota, cost, and alternative path.

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

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

An output schema exists so return values need not be elaborated. The description covers the full lifecycle, constraints, alternatives, and edge cases, making the tool callable without additional investigation. Nothing essential is missing.

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

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

Schema coverage is 100% and both parameters already have clear descriptions and an enum for content_type. The description adds useful context like the 10 MB limit and the fact that file_name becomes the hosted file name, but this is mostly reinforcing rather than deeply extending the schema semantics.

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

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

The description states a specific verb and resource: it 'prepares the upload of an image file' and explicitly connects it to set_article_cover_image and upload_article_image. It clearly distinguishes when this tool is needed versus when it is not, which separates it from sibling tools.

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

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

The description gives explicit when-to-use guidance: use it when an image has no public URL and you need to pass it to set_article_cover_image or upload_article_image. It also names the alternative explicitly ('pass image_url directly') when a URL already exists, so an agent knows exactly when to avoid 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?

Beyond destructiveHint=true, it reveals irreversibility ('permanently'), the refusal guard for keywords with generated articles, and a nontrivial side effect: scheduled articles targeting deleted keywords are kept and their ids returned for headline regeneration. This is meaningful behavioral context absent from structured metadata.

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

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

Four sentences, each carrying information: the destructive action, the refusal condition, the side effect on scheduled articles, and the website_id guidance. It is front-loaded and has 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?

Given annotations, a full input schema, and an output schema, the description covers the key operational details an agent needs: what gets deleted, when the call is rejected, and what happens to scheduled articles. No critical calling behavior is left unexplained.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds only a slight reminder to pass website_id in multi-website accounts, mirroring the schema's own note, and provides no additional meaning for keyword_ids beyond what the schema already states.

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 'Permanently deletes keywords from the website,' a specific verb+resource action that clearly separates it from siblings like add_keywords and delete_scheduled_article. The scope and irreversibility are 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?

It states when to pass website_id ('when the account has several websites') and gives an explicit when-not condition: the call is refused if any keyword already has a generated article. It does not explicitly name alternative tools for those blocked cases, so it stops just short of perfect 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 indicate destructiveHint=true and idempotentHint=true, but the description adds beyond those: it clarifies irreversibility, that rows already generated are refused, and that no refund occurs because scheduling never charged anything. These are valuable behavioral details not covered by annotations. The only minor gap is not detailing the exact response on success or failure, but that is covered by the output schema. No contradiction found.

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

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

The description is four sentences, each with a distinct purpose: action, irreversibility, edge case (generated rows), and guidance on website_id. It is concise and front-loaded with the primary action verb. The only minor inefficiency is repeating the 'scheduling' context in the refund sentence, but it's still useful. Overall, it's well-structured and earns a 4.

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 a destructive, irreversible operation with an output schema and full parameter coverage, the description covers all essential aspects: what it does, limits (only pending articles), irreversibility, refund policy, and the conditional parameter. It could mention what happens on attempting to delete a non-existent ID, but the output schema likely covers that. It is complete enough for an agent to call correctly, earning a 4.

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

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

Schema description coverage is 100%, so both parameters are described in the schema: 'scheduled_article_id' from list_scheduled_articles and 'website_id' from get_account. The description adds the crucial conditional logic for 'website_id' (required when multiple websites) and clarifies that 'scheduled_article_id' is for a pending article, but these are mostly redundant with the schema. The description does not add format or syntax details beyond what the schema provides, so a 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 starts with a clear verb ('Unschedules an article') and specifies the resource ('a pending article from the content calendar'). It clearly distinguishes from 'reschedule_article' (which would reschedule) and 'update_scheduled_article' (which edits rather than deletes), and it explicitly contrasts with 'generate' and 'archive' operations.

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

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

The description explicitly states when to use this tool: 'removes a pending article from the content calendar', and when not to: 'Refuses rows that were already generated (use the articles tools to archive those)'. It also provides a conditional instruction ('Pass website_id when the account has several websites') and references 'get_account' for context. This is comprehensive and leaves no ambiguity.

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 far beyond annotations by disclosing synchronous slow execution ('one to several minutes, wait for it instead of retrying'), the Out of Sync side effect and remedy, credit charging and refund policy, subscription requirement, and the cost-estimate behavior when confirm is omitted. The destructiveHint is consistent with these details; no 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?

The description is dense but every sentence earns its place. It front-loads the core action and then methodically covers timing, side effects, costs, prerequisites, and parameter conditions without fluff.

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 slow, destructive, credit-charging AI editing tool with 6 parameters, the description covers all critical operational aspects: duration, charging behavior, side effects, prerequisites, and parameter usage. An agent has everything needed to invoke it safely and correctly; the output schema handles return-value specifics.

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

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

Even though schema coverage is 100%, the description adds essential semantics: locale target selection, per-locale credits for also_apply_to_locales, confirm's dual role (acknowledge vs. cost-only response), and website_id's condition. It also clarifies instructions with concrete examples ('tone, length, add a section, fix facts...').

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: 'Rewrites an article's body with AI... and saves it.' The description also names sibling alternatives (batch_edit_articles_with_ai, update_* tools), so an agent can immediately distinguish this tool from related ones.

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 when-to-use and when-not-to-use guidance: 'Use batch_edit_articles_with_ai for many articles, and the update_* tools for headline, meta description or slug.' Also explains when to pass confirm, website_id, and locale, making invocation decisions clear.

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

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

The description discloses non-obvious behavior beyond annotations: credit is charged upfront and refunded only on provider failure, zero qualifying ideas still consume the credit, near-duplicates/navigational/other-city keywords are dropped, and a keyword without a cluster becomes the pillar of a new one. This is far richer than the annotations alone and does not contradict them.

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

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

The description is dense but every sentence carries necessary operational detail: main behavior first, then credit mechanics, confirmation requirement, and website_id condition. There is no filler or repetition.

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

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

For a mutating tool with cost implications, the description covers prerequisites, confirmation behavior, refund policy, filtering logic, and parameter conditions. Combined with 100% schema coverage and the presence of an output schema, nothing essential is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mostly restates what the schema already says about confirm, keyword_id, and website_id, though it does add the multi-website condition nuance. It does not materially exceed the schema's 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 states a specific verb and resource: 'Grows the topic cluster of a keyword' and explains the concrete behavior (fetches related ideas, filters for semantic closeness, adds at most 30). This clearly differentiates it from sibling tools like research_keywords or add_keywords, which serve different purposes.

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 operational context: confirm=true is required to acknowledge the credit charge, without it only the cost and balance are returned, and website_id is needed for multi-website accounts. It does not explicitly mention when to prefer this tool over alternatives, 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?

Even though annotations already declare readOnlyHint, idempotentHint, and destructiveHint, the description adds substantial behavioral detail: the exact cannibalization algorithm, the maximum of 200 keywords, the deterministic suggestion logic, the prerequisite of a recent sync, and the non-silent handling of a missing Search Console connection. This goes well beyond the annotations and helps the agent predict side effects and edge cases.

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 long but densely informative; every part relates to correct invocation or interpretation. It front-loads the core purpose before elaborating on the algorithm, output fields, prerequisites, and alternatives. It could be slightly more scannable with structural breaks, but it avoids fluff and repetition.

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

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

For a tool with this complexity, the description covers prerequisites, input semantics, output shape, edge cases, and alternatives. It even explains the meaning of different suggestion reasons and how scheduled articles are represented. The presence of an output schema helps, but the description still independently supplies enough context for an agent to invoke and interpret results 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%, with each parameter already documented. The description adds marginal context by explaining include_planned's effect and the website_id requirement for multi-website accounts, but most of this is a paraphrase of the schema. The added 'best position first' ordering note is useful but not substantial enough to push above baseline.

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

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

The description opens with a clear, specific action: 'Finds tracked keywords for which two of the site's own pages will compete.' It defines the resource (tracked keywords) and the exact outcome, and it explicitly differentiates from Search Console's definition and from sibling tools like get_keyword_rankings. There is no ambiguity about what this tool produces.

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 states concrete when-to-use conditions: it requires a recent Search Console sync, ignores snapshots older than 30 days, and returns a message when Search Console is not connected. It also names alternatives explicitly: 'Not a rank tracker: use get_keyword_rankings for positions and get_keyword for one keyword's articles.' This gives the agent clear 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?

Even though annotations already mark it read-only and idempotent, the description adds substantial behavioral context: websites where the user is only a member are never available over MCP and not listed, credits cannot be bought through this server, and the return includes credit balances and subscription details. This goes well beyond the annotation hints.

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 long sentence but it is dense and information-rich, starting with 'Recommended first call' and systematically covering websites, roles, credits, and plan. It could be split for easier scanning, but no sentence or clause 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?

With zero parameters, strong annotations, and an output schema present, the description is complete. It explains the return semantics, the website_id dependency for other tools, and the credit purchase limitation, giving the agent everything needed to decide when and how to call it.

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

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

The tool has zero parameters, so there is no parameter-level semantics to explain. The description appropriately focuses on what the response contains, which is the relevant semantic content for a no-input tool.

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: it 'Returns the signed-in user's email and every website this connection may use' with detailed fields. It explicitly positions itself as the 'Recommended first call,' differentiating it from account-related siblings like get_credit_balance and get_website_settings.

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

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

The description gives clear usage context: it is 'Recommended first call' and explains that website_id is 'needed by the other tools' when multiple websites exist. It does not name specific sibling alternatives or state when not to use it, but the first-call guidance effectively signals when to invoke 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the status lifecycle, the is_stale flag meaning the article body changed without re-verification, and the fact that it is 'Free and instant.' It does not describe pagination or exact return shape, but the output schema exists and the status semantics are well disclosed.

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

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

The description is dense but well-organized: it front-loads the core purpose, then enumerates statuses, then report contents, then the staleness flag, then cost and the website_id condition. Every sentence earns its place 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 read-only retrieval tool with a rich output schema, the description covers the status lifecycle, staleness semantics, cost, and the conditional parameter. The only minor omission is an explicit note that the report is for the default-language version, which is actually included. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters with source references (article_id from list_articles, website_id from get_account). The description adds the conditional rule for website_id ('when the account has several websites'), which is useful, but it does not add much beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Reads the stored competitor-relative SEO analysis of an article (default-language version).' It clearly distinguishes this from running a new analysis (siblings run_advanced_seo_check, run_advanced_seo_check_for_content) by emphasizing 'stored' and 'status' states. The scope is precise and an agent can tell it apart from check_article_seo_score and check_seo_score.

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

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

The description gives explicit status-based guidance: 'pending or processing (poll again in a minute), failed (error included, credit refunded) or done.' It also states when to pass website_id: 'Pass website_id when the account has several websites (see get_account).' This is clear when-to-use guidance with a pointer to a sibling for context.

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

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

Even though readOnlyHint, idempotentHint, and destructiveHint are already provided, the description adds meaningful behavioral detail: rates are percentages, null when nothing was checked, pending states during checks, and a failure mode with an activation link when the add-on is not active. This goes well 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?

The description is long but densely packed with non-redundant information: purpose, outputs, parameter behaviors, failure conditions, read-only nature, and sibling distinction. Every sentence carries useful operational meaning, and the main purpose is 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?

The tool is complex with four optional parameters and a rich output, yet the description covers all relevant behaviors, defaults, failure modes, and parameter effects. It also handles the multi-website case by referencing get_account. Nothing an agent needs to decide whether and how to call the tool is missing.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds value by explaining the effect of parameters on the output, e.g., 'Pass surface to restrict every number to one platform' and 'include_answers=true for the latest answer text per prompt.' This provides semantic context beyond the bare schema descriptions.

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

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

The description opens with a specific verb and resource: 'Reads the AI Visibility dashboard of the website: how often AI assistants... mention and cite the brand.' It clearly states what data is returned and distinguishes itself from siblings, notably saying it is not Google Search Console data and pointing to get_keyword_rankings for that.

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 includes explicit usage guidance: when to pass surface, include_answers, and website_id, and that the tool cannot add prompts or competitors. It explicitly routes the user to get_keyword_rankings for Google Search Console data, making the when-not-to-use case 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?

Annotations already establish readOnly/idempotent/non-destructive, so the bar is lowered, yet the description adds real value: "Never contacts the CMS" clarifies the data source, and the warning that the content body "can be long" prepares the agent for payload size. It also notes the sharing semantics of status/slug across locales.

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 return contents, then the optional-parameter guidance, with no filler sentences. The field enumeration and locale/cross-locale notes make it somewhat dense, but 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?

An output schema exists so return values need not be explained, yet the description covers the locale fallback, the multi-website disambiguation via website_id, and the content-size caveat. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: main_image_alt and the base status/slug are shared by every locale, and include_content can yield a long body. That sharing behavior is not captured in the parameter descriptions themselves.

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 ("Returns one article") and enumerates the returned fields, which lets an agent distinguish it from list_articles without opening the schema. The scope is single-article retrieval, clearly separated from the sibling list/batch 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 explicit conditions for the optional parameters: include_content for the markdown body, locale to read a translation, website_id when the account has several websites, plus a pointer to get_account. It does not name a competing alternative tool directly, but the context needed to invoke it correctly is present.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false; the description adds that backlinks are matched automatically and there is nothing to trigger, setting the expectation that this tool performs no action. It also discloses a bounded result of the last 20 backlinks. No contradiction with annotations.

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

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

Three sentences, each earning its place: return payload, usage context, and parameter condition. The most important information is front-loaded with 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?

The output schema covers return values, the single optional input parameter is well documented, and annotations cover safety. The description adds usage context and parameter guidance, so 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?

The schema fully documents website_id as optional and sourced from get_account. The description reinforces when to pass it (accounts with several websites), but this is essentially the same information, so with 100% schema coverage 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?

Clearly states the tool returns the website's backlink exchange status and enumerates the exact contents: Domain Rating, credit balance, status counts, and last 20 backlinks with linking site, anchor, and target page. It does not explicitly differentiate itself from sibling tools like check_backlinks, so it stops short of a 5.

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

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

Provides a direct use case: report on link building progress, and notes that backlinks are matched automatically with nothing to trigger, telling an agent this is a passive read rather than an action. It does not mention when to prefer sibling tools such as check_backlinks, so no exclusions are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is fully covered. The description adds meaningful context about what the returned credits mean and confirms this is a current-state read. No contradiction with annotations exists.

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

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

The main result is front-loaded in a single focused sentence, with compact parenthetical definitions for the fields and a direct parameter condition. Every phrase earns its place; 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?

Given one optional parameter, a full output schema, and strong read-only/idempotent annotations, the description provides everything an agent needs to select and invoke the tool correctly. It covers field semantics and the only parameter condition without requiring extra 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 schema already documents website_id with 100% coverage, including that it comes from get_account and is optional for single-website accounts. The description restates this guidance ('Pass website_id when the account has several websites') without adding new format, constraints, or defaults.

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 ('Returns') and a clear resource ('the website's current credit balances'), and it enumerates the exact fields returned: ai_brain_credits, articles_credit, backlink_credits, and has_active_subscription. This makes the tool's purpose unambiguous and distinguishes it from all sibling tools.

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

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

It gives clear context for invocation by stating when to pass website_id ('when the account has several websites') and directs the agent to get_account for the id. It does not explicitly contrast alternatives, but no sibling tool appears to perform the same credit-balance lookup.

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

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

Adds substantial context beyond annotations: it triggers a re-check like the Refresh status button (explaining why readOnlyHint is false despite being a 'get'), enforces a 30-checks-per-hour rate limit, is free, and has a 5-60 minute propagation window. This is exactly the side-effect, quota, and timing disclosure an agent needs.

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

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

The paragraph is front-loaded with the action and its result, then layers operational details (timing, rate limit, param guidance). It is dense and largely earns its length, though the long parenthetical status list borders on redundant given the output schema.

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

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

A complete picture for a single-optional-param status tool: it covers behavior, timing, limits, and cost, and an output schema handles return-value structure. Only auth/permission prerequisites are unstated, a minor 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?

Schema coverage is 100%, so the baseline is 3, but the description adds routing guidance not present in the schema: pass website_id when the account has several websites and consult get_account to obtain it. That meaningfully improves correct invocation.

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

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

States a specific verb+resource (re-check the hosted blog's DNS and certificate) and precisely enumerates what it returns, including concrete status strings. An agent can distinguish it from create_hosted_blog or get_website_setup_guide 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 explicit operational guidance: poll every few minutes after adding the record, DNS changes take 5-60 minutes, and pass website_id when the account has multiple sites (pointing to get_account). It lacks an explicit 'when not to use' or named alternative for checking status, keeping it just 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 indicate read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral context beyond those hints: the 90-day per-day/per-country history, the up-to-20 sibling keyword limit, the inclusion of scheduled and generated articles, and the empty-history edge case when GSC is disconnected.

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

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

Three sentences, each earning its place: the return payload, the important edge case, and the conditional parameter guidance. The most decision-relevant information is 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?

For a single-keyword retrieval tool with a read-only annotation and an output schema, the description is complete. It covers what is returned, the limit on sibling keywords, the GSC dependency, and the parameter condition the agent needs to make a correct 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% and the schema already describes both parameters. The description adds a practical condition for website_id ('Pass website_id when the account has several websites') and references get_account, giving the agent actionable selection logic beyond the schema's static descriptions.

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

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

The description opens with a specific verb and resource: 'Returns one keyword with its metrics...' It clearly enumerates the exact payload components (metrics, 90-day position history, articles, sibling keywords), which differentiates it from siblings like list_keywords, get_keyword_rankings, and get_keyword_trends.

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

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

The description gives clear contextual usage guidance: it tells the agent when to pass website_id ('when the account has several websites') and warns when position history will be empty ('when Google Search Console is not connected'). It does not explicitly name alternatives or state when not to use this 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?

Annotations already indicate read-only, idempotent, and non-destructive behavior, so the description's added value comes from extra context: data freshness follows the Search Console sync cadence with a reference to gsc_last_synced_at, unranked keywords are excluded when either position bound is set, the 30-day historical point is conditionally included, and the tool reports an unconnected GSC instead of returning empty positions. These are meaningful edge-case behaviors beyond the annotations and are not contradicted.

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 long but every sentence earns its place: it opens with purpose, defines the data fields, explains filters and sort semantics, gives a ready-to-use query, names the alternative tool, and closes with connection-status and website_id guidance. The structure flows logically from what the tool returns to how to shape a request, and the density is appropriate for an 8-parameter read-only tool.

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

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

Given the tool's complexity, the presence of an output schema (which covers return-value details), and read-only annotations, the description covers the remaining operational context: data freshness, server-side filtering, historical data availability, alternative use cases, error behavior when GSC is disconnected, and the multi-website case. An agent has everything needed to select and call it correctly without further lookups.

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?

Although the schema already covers 100% of parameters with descriptions, the description layers on significant additional semantics: the unranked-exclusion behavior when position_min or position_max is set, the explicit CTR formula, the interpretation of country defaults to snapshot country or a lowercase alpha-3 code, and the practical example showing how to combine filters and sort. This goes beyond simple parameter documentation and materially improves correct invocation.

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

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

The description clearly identifies the tool as a rank-tracking view from Google Search Console for the website's tracked keywords, stating exactly what is returned (current average position, page ranking, clicks, impressions, CTR, country, last sync time). It also differentiates from get_keyword_trends by explicitly stating it is not for changes over time, so an agent can correctly choose between siblings.

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

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

It provides explicit when-to-use guidance: 'Not for changes over time: use get_keyword_trends for click, impression and position deltas between periods.' It also gives a concrete recipe for a common use case ('Page-2 quick wins: position_min 5, position_max 15, min_impressions 200, sort impressions') and explains when website_id is required, which is actionable and leaves 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?

Annotations already mark the tool as read-only and idempotent, and the description adds substantial behavioral context beyond that: it explains the 2–3 day data lag, that keywords without history are omitted, that position is null when a window has no impressions, that by_page is computed before the top cut, and that it surfaces a 'not connected' state instead of silently returning empty rows. This is exactly the kind of non-obvious behavior an agent needs.

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

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

The description is long but information-dense, with every sentence contributing a distinct fact: comparison windows, metrics, grouping, sorting, defaults, country handling, data lag, exclusions, and error behavior. It is front-loaded with the core purpose before covering parameter behavior and use boundaries.

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

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

Given the tool's moderate complexity, the presence of an output schema, and rich annotations, the description covers all expected context: window semantics, defaults, exclusions, data freshness, edge cases for missing impressions, and alternative tools. An agent can select and invoke this tool correctly without additional documentation.

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?

Although the schema has 100% parameter description coverage, the tool description adds operational meaning beyond the schema: sort options map to concrete meanings, default country behavior falls back to each keyword's snapshot country, by_page is applied before the top cut, and keyword_ids max 200 can be omitted to include all tracked keywords. These details are not inferable from the schema alone.

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 resource (Google Search Console keyword trends) and a precise operation: comparing the last window_days against the prior window_days with per-keyword metrics and deltas. It also explicitly contrasts itself with get_keyword_rankings and list_keywords, so it is clearly distinguishable from siblings.

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

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

The description gives explicit when-to-use guidance ('answers which pages are losing traffic') and provides direct exclusions with named alternatives: 'Not for the current position or ctr (use get_keyword_rankings) nor volume and difficulty (use list_keywords).' It also clarifies the sync cadence and the Search Console connection failure behavior, leaving little ambiguity about when to invoke 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable context about what the contract contains (headers, payload, retry semantics, etc.) and that it's free, which is not in the annotations. However, it does not disclose any potential side effects (there are none) or rate limits, which are not critical given the read-only nature.

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, dense sentence that front-loads the core purpose and lists the contract components without fluff. It is efficient and earns its length, though it could be broken into two sentences for readability. The 'Free.' note is a minor addition. Overall, it is concise and structured.

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-parameter, read-only documentation tool with an existing output schema (indicated by 'Has output schema: true'), the description is complete. It states when to use, what the contract covers, and the cost implication. 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?

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameters, and the schema coverage is 100% trivially. It does add context about the returned content, but that is not parameter semantics. Thus a 4 is appropriate.

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

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

The description states a specific verb ('Returns') and a clear resource ('the custom webhook contract an endpoint must implement to receive BlogSEO articles'), listing the key elements (headers, payload, multi-language, retry semantics, secret verification, etc.). It clearly distinguishes this from sibling tools like connect_custom_webhook and test_custom_webhook by focusing on the specification of the contract.

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

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

The description explicitly instructs the agent to 'Read it before writing or reviewing a webhook receiver,' which is a clear when-to-use directive. It also notes the tool is free, removing any cost concern. No exclusion or alternative is necessary since this is the definitive source for the contract.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by detailing the exact structure of the returned object and noting that some fields are read-only facts, which helps the agent interpret data correctly. It does not mention any side effects or pagination, but for a settings getter with a small payload, this is sufficient.

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

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

Three sentences with no wasted words. The first sentence states purpose and enumerates content, the second gives usage guidance, and the third covers the parameter condition. The most critical information (purpose and usage) is front-loaded, and the grouping list is dense but useful.

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

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

Given the tool's complexity (a settings object with multiple nested groups), the description provides a complete enumeration of fields, making it self-sufficient for an agent to know what to expect. It also provides the necessary usage context (before updates) and parameter condition (multiple websites). With an output schema present, the description does not need to explain return format, and nothing essential is missing.

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

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

Schema description coverage is 100%, and the schema already states 'Website id from get_account. Optional when the account has a single website.' The description repeats this ('Pass website_id when the account has several websites') without adding new semantics. Since the schema fully documents the parameter, the description earns the baseline 3 without extra credit.

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

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

The description opens with a specific verb and resource: 'Returns the website's configuration grouped as it appears in the app.' It then enumerates all configuration groups (info, general, content, images, competitors) with their key fields, making the tool's purpose unmistakable. It also implicitly distinguishes itself from the update_* siblings by instructing to read it before updates.

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 states when to use the tool: 'Read it before calling an update_* tool so you only change what the user asked for.' This is a clear directive that positions the tool as a prerequisite for any mutation. It also gives conditional guidance for the parameter: 'Pass website_id when the account has several websites (see get_account),' referencing the correct sibling for context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context: it returns a guide (not performing the setup), notes it is free, and describes the two setup options. This goes beyond the annotations without contradicting them.

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

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

Three concise sentences that front-load the purpose, list the options, and give clear next-step instruction. Every sentence earns its place with zero 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 an output schema present and no parameters, the description is fully sufficient for an agent to decide when to call this tool and what to expect. It even mentions the two branches of the guide and the follow-up tools, making it a complete entry-point definition.

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

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

There are zero parameters and schema coverage is 100%, so the baseline for no parameters is 4. The description adds no parameter-specific details because none exist, but it effectively conveys the tool's purpose without needing parameter context.

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

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

The description clearly states it returns a guide for connecting a custom-built website so articles get published, with specific frameworks mentioned. It distinguishes itself from action tools by being the guide that precedes them, and names the two options (hosted blog vs webhook) within the description.

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 to call it first when the user asks to plug, connect or integrate a website, then follow its steps with the tools it names. This provides clear when-to-use guidance and implies alternatives (the actual setup tools) are used after following the guide.

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

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

The description goes far beyond annotations: it discloses the destructive nature (body replaced in place, previous version not kept), the 1-3 minute synchronous wait, the cost of 1 AI brain credit charged after work and not refunded, the 'Out of Sync' side effect for published articles, and the failure-without-charge behavior. It also states return values (previous_score, new_score, instructions). This is thorough and consistent 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?

The description is long but every sentence carries necessary information. It is well-structured, starting with the main action, then exclusions, timing, destructive nature, side effects, returns, cost, confirm, and website_id. No redundancy; it earns its length given the tool's complexity.

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 4 parameters and significant behavioral caveats, the description covers all necessary aspects: purpose, process, exclusions, timing, destructive effects, side effects, costs, confirm requirement, locale handling, and return values. An agent has everything needed to call it correctly and interpret 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context: locale is for translations, confirm must be true to proceed (otherwise only cost/balance returned), and website_id is optional for single-website accounts. This clarifies usage beyond the schema descriptions.

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

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

The description clearly states the tool rewrites the article body with AI to fix failing on-page SEO checks, and outlines the entire process (score, rewrite, re-score). It explicitly excludes title, meta description, slug, links, and images, and directs users to update_* tools for those, effectively differentiating from siblings like update_article_content or edit_article_with_ai.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: use it for body-level SEO improvement, but use update_* tools for title/meta/etc. It also covers prerequisites (active subscription/trial), the need to pass confirm=true to acknowledge charges, and website_id for multi-website accounts. It notes the tool is slow and advises waiting rather than retrying.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses key behaviors: it is synchronous and slow (1-3 min, wait, don't retry), has a rate limit (20 calls/hour/website), costs 1 AI brain credit charged after work and not refunded on failure, requires subscription or trial, and preserves topic, facts, tone, language, links, and images. It also states the output format (improved markdown and score before/after). This fully informs the agent of side effects, latency, cost, and constraints.

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

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

The description is dense but every sentence earns its place. It opens with the core action and scope, then moves to output, usage, failure behavior, latency, rate limits, cost, auth, and a parameter hint, in a logical order. There is no fluff or repetition; it is a compact, well-structured paragraph that front-loads the most critical information.

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

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

Given the tool's complexity (8 params, output schema, multiple constraints), the description covers all necessary context: what it does, when to use it, how to handle the result, failure conditions, latency, rate limiting, cost, auth, and parameter specifics. Since an output schema exists, the description appropriately does not restate return structure but adds the score-before/after detail. Nothing an agent needs to correctly invoke 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?

The schema already provides descriptions for all 8 parameters (100% coverage), so the baseline is 3. The description adds extra value by clarifying the inline nature of the content ('content you pass inline') and by giving specific guidance for website_id ('Pass website_id when the account has several websites (see get_account)'). It also explains the relationship of target_keyword to the checks. These additions lift it above the baseline, though not dramatically.

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 ('rewrites'), a resource ('content you pass inline'), and the precise goal ('fix failing on-page SEO checks') while enumerating the checks (keyword in intro, subheadings, density, etc.). It distinguishes itself from the sibling edit_article_with_ai by explicitly noting it works on inline content and not stored articles, so an agent can immediately tell what it does and what it does not do.

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

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

The description gives explicit when-to-use guidance: it states that content does not need to be in BlogSEO, that nothing is saved, and that for stored articles one should use edit_article_with_ai. It also warns that the tool fails before charging when all body-level checks pass, preventing wasted calls, and provides rate-limit and cost details. This is a model of usage direction.

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 idempotentHint=true, covering the safety profile. The description adds substantial behavioral context beyond annotations: it specifies the ordering, page size, summary-only return, absence of a total count, and the meaning of statuses (preview_failed = failed to publish, preview_draft = published in draft). These details inform the agent about the tool's output and paging contract, which annotations do not provide. No contradiction with annotations.

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

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

The description is three sentences long and every sentence earns its place. It front-loads the core listing behavior (newest first, 20 per page, status and keyword) before moving to filters, then to return behavior and pagination, and finally to the website_id nuance. There is no fluff or repetition, and the structure is logical and easy to parse.

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

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

Given the presence of an output schema (not shown but indicated) and annotations covering the safety profile, the description covers everything an agent needs to call this tool correctly: what it lists, filtering options, pagination semantics, the summary-only return, how to get full content, and when to pass website_id. It also explains the meaning of statuses that might otherwise be opaque. No essential usage information 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 each parameter has a basic description. The tool description adds meaningful semantics beyond the schema: it clarifies the status enum values (preview_failed and preview_draft are explained), explains that website_id is optional when the account has a single website, and clarifies the date range filtering is inclusive. It also explains the pagination behavior tied to the page parameter and has_more, which the schema does not. This adds value beyond the structured schema.

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

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

The description clearly states the tool lists generated articles with a specific ordering (newest first), pagination (20 per page), and the fields returned (publication status and target keyword). It distinguishes itself from get_article by explicitly saying it returns summaries only and directing the agent to call get_article with include_content=true for full body content. This is a specific verb+resource with clear scope and differentiation from siblings.

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

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

The description provides explicit usage guidance: it names the alternative tool (get_article) and the condition for using it (to read an article's body), explains pagination behavior (keep paging while has_more is true) since there is no total count, and instructs when to pass website_id (when the account has several websites, referencing get_account). It also enumerates the available filters (search, status, date range). This leaves no ambiguity about when and how to use the 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: credentials and tokens are never returned, and it clarifies the scope (organization-level integrations plus the website's Search Console connection). It doesn't describe pagination or response shape, but the output schema exists and the added context is meaningful.

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 information-dense but well-organized: it front-loads what is listed, then gives the use case, then exclusions and alternatives. It is longer than strictly necessary, but every sentence earns its place by adding routing or behavioral context. The structure is logical and scannable.

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 list tool with one optional parameter, an output schema, and strong annotations, the description is complete. It covers what is returned, the use case, the key exclusion (no credentials/tokens), the conditional parameter usage, and the relevant sibling tools. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents website_id well. The description adds context beyond the schema by explaining when to pass website_id ('when the account has several websites') and pointing to get_account as the source. This is a small but useful addition over the schema.

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

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

The description clearly states the tool lists CMS, e-commerce, webhook integrations and the Google Search Console connection, with specific attributes (provider, connection status, auto-publish, draft-mode flags, publishing targets). It distinguishes itself from sibling tools by naming connect_custom_webhook and create_hosted_blog as alternatives for connecting, and get_account for website_id context.

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

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

The description explicitly says when to use this tool: 'Use it to know where articles get published and whether Search Console analytics are available.' It also provides exclusions: credentials/tokens are never returned, and it names alternatives for connecting integrations (connect_custom_webhook, create_hosted_blog) and notes other integrations are connected/disconnected in the app. It also gives a conditional usage rule: pass website_id when the account has several websites.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds valuable behavioral context: pages of 50, default sort by opportunity, position sorted best-first with unranked last, null positions when Google Search Console is not connected, and the fact that keyword_id is reused by other tools. This is exactly the kind of context that goes beyond structured annotations.

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

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

The description is dense but every sentence carries operational value: returned fields, pagination, sorting, filtering, null behavior, downstream ID usage, and multi-website prerequisite. It is front-loaded with the core purpose and does not waste words on tautology or 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?

Given an output schema already exists and there are 5 optional parameters, the description covers all call-time decisions: pagination size, sort options and default, filtering approach, website_id prerequisite, null positions edge case, and the tool's role in the broader keyword toolset. No essential information for invoking the tool correctly is missing.

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

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

Schema description coverage is 80%, so the baseline is 3andar; the description earns above baseline by adding semantics not present in the schema: page size of 50, sort order details ('position (best first, unranked last)'), default sort by opportunity, and the account-specific reasoning for website_id. Some overlap exists for search and favorites_only, but the added context is meaningful.

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

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

The description uses a specific verb and resource, 'Lists the website's tracked keywords', and enumerates the exact fields returned, which leaves no ambiguity about what the tool does. It further differentiates the tool from siblings by stating that it returns keyword_id values used by every other keyword tool, establishing it as the canonical listing endpoint.

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

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

The description gives clear operational context: pagination, supported sort orders, filtering options, and when to pass website_id ('when the account has several websites'). It doesn't explicitly name alternatives or state when-not to use it, but the role as the source of keyword_id values strongly implies when it is needed.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds value by disclosing pagination (50 rows per page with has_more) and ordering by date. No contradictions with annotations; these details are not present in structured fields.

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 sentence that front-loads the purpose and includes essential details (defaults, pagination, website_id). It is concise, though a minor typo ('60Returns') slightly detracts from polish.

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

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

With an output schema present, return values need no explanation. The description covers pagination, ordering, defaults, and the website_id condition, which is sufficient for a read-only tool with four optional parameters. It is complete enough for an agent 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's note about website_id (pass when account has several websites) largely echoes the schema description for that parameter, adding no significant new meaning. Defaults are also restated from the schema.

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

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

The description clearly states the tool lists the content calendar of a website, specifically articles scheduled for generation, with a row per day slot ordered by date. This distinguishes it from siblings like list_articles and schedule_article, making its purpose unambiguous.

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

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

Provides clear context for when to use (viewing scheduled articles) and gives a specific parameter guideline (pass website_id for multi-website accounts). However, it does not explicitly name alternatives or state when not to use this tool, falling short of the highest 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?

The description openly discloses that publishing is asynchronous, runs in the background within a few minutes, and requires polling get_article until status is published or Failed to publish. This goes well beyond the basic annotations, which only indicate the operation is non-read-only, non-idempotent, and non-destructive.

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

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

The description is dense yet well-structured, front-loading the core purpose before detailing eligibility, async behavior, and the website_id caveat. Every sentence adds necessary operational context, and no filler is present.

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

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

The tool has meaningful complexity around provider selection, article eligibility, async execution, and failure handling, and the description covers all of these. Since an output schema exists, the description does not need to explain return values, and it even points to get_account and get_article for related 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?

Schema coverage is 100%, but the description adds meaning around provider behavior by explaining how omission works and when eligible options are returned. It also clarifies the role of website_id in multi-website accounts, adding context beyond the bare schema descriptions.

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

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

The description clearly states the tool queues an article for publishing to connected integrations, naming specific providers like WordPress, Shopify, Webflow, and webhook. It distinguishes itself from the sibling sync_article_to_cms, which is explicitly referenced for pushing edits to a CMS, so an agent can tell the tools apart.

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

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

The description provides explicit guidance on when to use this tool versus sync_article_to_cms, including the eligibility of draft, live, generated, and failed-to-publish articles. It also explains provider-omission behavior and when to pass website_id, giving the agent clear decision criteria.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, but the description adds substantial behavioral context beyond them: a 2-3 day data lag, a 200 calls/hour/website rate limit, a 500-row cap per call, that filters/sort apply only to the top 25000 rows by clicks, and that a 'more rows' signal is returned. It also explains the error content when Search Console isn't connected.

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

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

Front-loaded with purpose and sibling differentiation, then constraints and examples. It is dense and long, but each sentence carries distinct information (limits, lag, row caps, examples, error behavior) rather than filler, so the length is largely earned though slightly overstuffed.

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 read tool with a full output schema and rich annotations, the description covers everything an agent needs: purpose, alternatives, examples, rate limits, data lag, pagination, ordering, and the row-cap semantics. Return-value explanation is unnecessary given the output schema exists.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning not in the schema: the ordering rules (by clicks, or by date when grouping by date only, unless sort is set) and the critical scoping note that min_clicks/min_impressions/position_min/position_max/sort operate only on the top 25000 rows. It also frames website_id via get_account and pagination via start_row.

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 (queries Google Search Console live) and names the exact metrics returned (clicks, impressions, CTR, average position) plus the supported groupings. It explicitly distinguishes itself from siblings get_keyword_rankings and get_keyword_trends by noting those only cover daily-synced tracked keywords while this reads live data.

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 alternatives and the condition that selects this tool over them, and supplies concrete when-to-use examples (one page's queries, positions 5-15 by impressions, brand vs non-brand, daily clicks, traffic-loss comparison across periods). It also notes it works on a website with no plan as long as Search Console is connected.

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

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

The description discloses the partial-failure behavior (provider-omitted keywords are left untouched), the credit cost and refund policy, the confirmation gate (without confirm=true it only returns cost and balance), and the subscription requirement. This goes well 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?

The core action is front-loaded, and each subsequent sentence adds a distinct fact about side effects, cost, prerequisites, or parameter conditions. There is no redundant wording.

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 mutating, paid refresh call with four parameters, the description covers when to use it, how costs are charged/refunded, how the confirm parameter changes behavior, how website_id disambiguates accounts, and what happens to unfetchable keywords. An output schema is present, so return-value details are not needed.

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%, but the description adds useful context: companion keywords must share the same website and locale, website_id is needed only when the account has several websites, and confirm controls whether the charge is acknowledged. This exceeds what the schema alone states.

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

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

The description names the exact resource and verb: it re-fetches monthly volume, difficulty, CPC, and opportunity score for one keyword plus up to 49 companion keywords of the same website and locale. It also distinguishes itself from plain getters by emphasizing it is a re-fetch that leaves missing provider keywords untouched and does not change Google Search Console positions.

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

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

It explicitly states the trigger: use it when metrics look stale, pointing to metrics_updated_at. It also clarifies what it does not do (change GSC positions) and the prerequisite of an active subscription or free trial, though it does not name a specific alternative tool to use 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?

The description discloses important behavior beyond the annotations: the operation is asynchronous and returns as soon as the job is queued, headlines appear within minutes, there is a strict rate limit of 3 requests per 24 hours per website, and at least one article credit is required. These are exactly the operational details an agent needs to avoid misuse.

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

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

The description is dense but efficient: every sentence adds unique value — purpose, when to use, async behavior, rate limit/credit requirement, and parameter handling. The most important functional information is front-loaded, and there is no redundant 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 single-parameter tool with an output schema, this description covers everything needed to call it correctly: scope, timing, constraints, prerequisites, and parameter conditions. The async return behavior and rate limit are especially important for managing agent expectations.

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

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

The schema already documents website_id and its 100% coverage, so the baseline is 3. The description adds meaningful guidance beyond the schema by instructing when to pass website_id (when the account has several websites) and pointing to get_account as the source, which compensates well for a sparse parameter set.

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, concrete action: it queues a rewrite of headlines for every upcoming automatically planned article that has not been generated yet. It also explicitly scopes out custom articles, which clearly distinguishes this tool from single-article headline tools like suggest_headline or update_article_headline.

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

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

It states when to use the tool: after changing the offer summary, audiences, or instructions so the calendar reflects those changes. It also gives an exclusion (custom articles are untouched), but it does not explicitly name an alternative tool for those excluded cases, so it stops short of full 5-level 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?

Annotation Contradiction: the description states 'Repeating a swap swaps the dates back,' meaning the same call can undo the previous result and the operation is not idempotent, while idempotentHint=true claims it is. The description otherwise discloses useful traits such as refusals, frequency enforcement, and return value, but the direct contradiction with the annotation forces the lowest score.

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

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

The description is front-loaded with the core action and packs swap behavior, frequency rules, refusal conditions, repeat behavior, return value, and website_id guidance into six dense sentences. 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 mutating reschedule operation, the description covers prerequisites, failure conditions, target-day conflicts, repetition semantics, multi-website handling, and return value; the output schema supplies return structure. It is complete for an agent to invoke and interpret the tool, aside from the annotation contradiction already flagged.

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%, providing baseline parameter documentation. The description adds meaning beyond the schema by explaining the effect of swap_with_scheduled_article_id ('exchange dates... instead of stacking') and the condition for website_id ('see get_account'). This exceeds the baseline without needing to restate formats.

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

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

The description opens with a specific verb and resource: 'Moves a scheduled article to another date (YYYY-MM-DD).' It clearly distinguishes this action from scheduling, updating, or deleting by focusing on the date move and the swap semantics, so an agent can tell it apart from siblings like schedule_article and update_scheduled_article.

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

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

The description gives clear conditional guidance: when to pass swap_with_scheduled_article_id, what happens without a swap, and when website_id is needed ('when the account has several websites'). It does not explicitly name sibling alternatives or state when not to use this tool, but the context is strong enough to select it correctly.

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

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

The description goes far beyond the annotations. It discloses the 5-calls-per-hour shared rate limit, that credit is charged even when nothing is added, the 1 AI brain credit cost charged after work and non-refundable on failure, the requirement of an active subscription or free trial, and the asynchronous background processing (clustering/intent may be empty for a minute). Annotations only indicate readOnlyHint false and openWorldHint true, so this description carries the full burden and exceeds it.

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

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

The description is dense but efficiently structured. It front-loads the primary purpose, then covers limits, async behavior, rate limits, costs, alternatives, and the confirm flag in a logical order. Every sentence delivers necessary information; there is no filler or redundancy, despite its 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?

For a tool with significant complexity—costs, rate limits, async processing, prerequisites, and alternatives—the description covers every aspect an agent needs to invoke it correctly. It explains the confirm requirement, subscription need, charge behavior, and background processing. An output schema exists, so return-value documentation is not required. 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?

The input schema already provides 100% coverage, with descriptions for seed_keywords ('Seed keywords to expand (1 to 20)'), confirm ('Set to true to acknowledge the AI brain credit charge...'), and website_id ('Website id from get_account...'). The description largely repeats these details and does not add new parameter-specific semantics beyond what the schema already conveys. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Discovers new keywords from seed keywords and adds them to the website.' It specifies the verb (discovers/adds), the resource (keywords), and the mechanism (seed expansion). It also distinguishes from siblings by naming add_keywords for specific keywords and refresh_keyword_metrics for metrics, so an agent can immediately tell this tool apart.

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

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

The description explicitly tells when to use this tool versus alternatives: 'To add specific keywords as written, use add_keywords; to look up metrics of existing keywords, use refresh_keyword_metrics.' It also explains the confirm flag behavior ('without it the tool only returns the cost and your balance') and the shared rate limit with add_keywords, leaving no ambiguity about invocation context.

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 readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, but the description goes far beyond by disclosing the asynchronous polling model (returns immediately, 1-2 minutes until done, poll get_advanced_seo_report), the refusal condition (already running), the cost (1 AI brain credit, charged upfront, refunded on provider failure), and subscription requirement. It also describes the side effect of storing a report, which is richer than the bare annotations.

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

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

The description is dense but every sentence earns its place: it starts with the core action, then covers async behavior, prerequisites, refusal, cost, subscription, and parameter guidance. There is no filler, and the structure flows logically from what → how → when → prerequisites → cost. Despite its length, it remains highly scannable and front-loaded with the primary purpose.

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

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

Given the tool's asynchronous nature, cost implications, required keyword precondition, and interplay with sibling tools, the description covers all necessary details: what the analysis produces, how to retrieve results (polling), when to rerun, and account context (website_id). While an output schema exists, the description also enumerates the report fields, ensuring an agent understands the outcome without needing to open 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?

The schema already provides 100% coverage: both parameters have descriptive text ('Article id from list_articles.' and 'Website id from get_account. Optional when the account has a single website.'). The description repeats the website_id guidance ('Pass website_id when the account has several websites'), which adds marginal value beyond the schema. Since the schema carries the meaning, the baseline of 3 is appropriate; the reinforcement does not elevate 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 precise verb ('Starts') and resource ('competitor-relative SEO analysis of the default-language article'), then specifies the exact steps (fetches top Google results, compares depth and topic coverage, stores a report). This clearly differentiates it from siblings like check_article_seo_score (which reads the report) and improve_article_seo (which acts on it), and the distinction is reinforced by the note that these tools use the benchmark automatically.

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

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

The description provides explicit when-to-use guidance: the article must have a target keyword, it is refused while an analysis is already running, and it should be re-run only when the article changed substantially (with a pointer to is_stale). It also instructs to pass website_id when the account has several websites (linking to get_account). While it does not name a direct alternative tool, it clarifies that check_article_seo_score and improve_article_seo consume the benchmark, so rerunning is unnecessary unless content changed.

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