Rankwise

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

Annotations declare the write/non-idempotent/open-world profile, and the description adds materially more: the crawl+score happens asynchronously in the background, the operation fails at the plan's domain limit, and it consumes no credits. Cost, failure condition, and async behavior are exactly the kind of context annotations cannot express.

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

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

Three short sentences, front-loaded with the action and followed by operational facts (async crawl, failure mode, cost). No repetition of the title or schema and nothing that could be cut.

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 the essentials an agent needs: what happens next, what makes it fail, and what it costs. It could still note duplicate-domain behavior, which the non-idempotent hint implies but the text never addresses.

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 'domain' and 'brand_domains' are already documented in the schema. The description adds no syntax, format, or cardinality detail beyond it, matching the baseline for a fully-covered schema.

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

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

States a specific verb and resource ('Start tracking a domain's AI visibility in this workspace') and implicitly scopes it against list_domains, remove_domain, and recrawl_domain. An agent can tell this is the create/onboard operation without opening the schema.

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

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

Gives clear context for invoking it — background crawl/scoring on seed, plan-limit failure, and no credit cost — which tells the agent when the call is appropriate and when it will fail. It stops short of naming sibling alternatives (e.g., recrawl_domain for existing domains, list_domains to check existence), so it is not a full 5.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false; the description goes further by explaining *why* it is idempotent ('keywords already planned are skipped, so a retry never adds twice') and by describing the scheduling side effects (day occupancy, unwritten card relocation, next free publishing day). It stops short of permission/auth or rate-limit details, but the annotation bar is already met.

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 tight sentences, front-loaded with the action and cap, then the scheduling rules and idempotency. Slightly telegraphic phrasing ('With a day it takes that day') costs a little clarity 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?

With an output schema present, return values need not be described, and the description covers the mutation's key side effects, limits and retry safety. It could still note whether the caller needs an existing planner or quota, but for a single-parameter tool this is close to complete.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning: it explains the 50-item cap and, crucially, the semantic difference between supplying a 'day' versus omitting it—a distinction the schema's date pattern alone does not convey.

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

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

States a specific verb and resource ('Add ... keywords to the Content Planner') and immediately clarifies the effect ('Each becomes a card'), which cleanly separates it from siblings like list_keywords, add_domain and add_question.

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

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

The context for calling it is implied (you want keywords scheduled in the planner) and the day/no-day branching is explained, but the description never names an alternative or states when not to use it (e.g. versus list_keywords or move_planner_card).

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 beyond the annotations by disclosing the downstream effect (scheduled checks ask AI engines whether they cite the brand), a failure mode ("Fails at the plan's question limit"), and cost transparency ("Free: it uses no credits"). Annotations already cover the read/write and idempotency profile, so this added operational context is the value layer.

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

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

Three tight sentences, front-loaded with the core action and example, followed by behavior and cost. Every sentence carries distinct information with no 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 (so return values need not be described) and annotations covering safety, the description supplies purpose, behavior, limit, and cost. Only the relationship to alternatives like list_questions/remove_question is missing, 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 description coverage is 100%, so the schema already documents domain_id, question, and locale fully. The description adds only an example question string, which marginally clarifies format but does not go beyond the schema baseline.

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

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

States a specific verb+resource ("Track a new question for a domain") and reinforces it with a concrete example of the question format. This is clearly distinguishable from siblings like add_domain, add_keywords, remove_question, and list_questions 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?

The purpose implies when to use it (adding a new tracked question versus removing/listing existing ones), but there is no explicit when-to-use statement and no named alternatives. Guidance is left to inference rather than spelled out.

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

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

Discloses behavior well beyond the annotations: credit debit with a pointer to get_plan_and_credits, that it launches an AI writing job that then waits for review, that nothing is published, the free re-approval path for failed generation, and the idempotency-key retry pattern. Annotations only give generic safety hints, so this description carries substantial additional 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?

Four short sentences, all front-loaded with the action and its effects; the cost pointer and idempotency guidance are tight and every clause adds operational value.

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

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

Output schema exists so return values need not be described, and the description covers cost, side effects, non-publication, and retry semantics. The only gap is brief_id semantics — e.g., whether it must be an existing draft — which the agent must infer.

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

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

Schema description coverage is 0%, so the description must compensate. It meaningfully explains idempotency_key (unique per call, reuse on retry) but adds nothing about brief_id beyond the schema's uuid format/pattern. One of two parameters is covered, leaving partial compensation.

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 (approve) and resource (draft brief) and immediately explains the consequence — debiting credits and kicking off AI draft generation that awaits review. This distinguishes it cleanly from siblings like create_brief, update_brief, archive_brief, and generate_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?

Gives clear context for when to use it: on a draft brief, plus the special case that re-approving a failed draft is free, and points to get_plan_and_credits for cost. It does not explicitly rule out alternatives (e.g., generate_article, publish_article), so it stops short of full when/when-not guidance.

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

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

Annotations already mark this as destructive and non-readonly, and the description adds meaningful behavioral context: approved briefs cannot be archived because credits were spent, the brief can be restored in the app, and its topic returns to the opportunity queue.

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

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

Three short sentences with the core eligibility rule front-loaded, followed by blocking condition and side effects. 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?

Output schema and annotations cover return shape and safety profile, while the description adds preconditions and side effects. The main remaining gap is that optional parameters reason and note are not explained.

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

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

Schema coverage is 0%, so the description needed to explain the parameters. It does not mention brief_id, reason, or note, and gives no guidance on the reason enum or note max length.

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: removing a draft brief that was never approved. It clearly distinguishes the eligible state from approved briefs, but does not explicitly name sibling tools such as approve_brief or update_brief.

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

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

It gives clear usage conditions: use for unapproved draft briefs only, and approved briefs cannot be archived. It does not point to alternative tools or explain what to do instead when archiving is blocked.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so safety is covered. The description adds genuinely non-derivable behavior: partial success semantics ('each article succeeds or fails on its own') and that the result enumerates both outcomes — important for a bulk destructive call, and not present in the annotations.

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

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

Two tight sentences, front-loaded with the operation and limit, then the failure-isolation contract. 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?

An output schema exists, so return-format detail is not required, and annotations cover the safety profile. The description still needs to carry the per-item parameter semantics it currently outsources to replace_article, which is the main remaining 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 description coverage is 0%, so the description is the only prose source, yet it tells the agent nothing about the per-item fields (article_id, html, slug, title, meta_description) beyond delegating to replace_article. It does add the 50-item bound and the array-of-articles shape, but the nested field semantics are left entirely undocumented.

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 (replace articles) plus scope (up to 50 per call), and differentiates itself from the single-item sibling replace_article via the bulk framing. The deferral 'same rules as replace_article' means the agent must consult that sibling for field-level meaning, which slightly weakens standalone clarity.

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

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

Usage is implied by the bulk framing and the explicit 50-item cap, which distinguishes it from replace_article, but there is no explicit when-to-use / when-not guidance, no prerequisites, and no statement of what happens if more than 50 are submitted.

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, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds real context beyond that: the data source (robots.txt), the non-exhaustive crawler set ('and others'), and that results are per-crawler. It omits rate-limit or network-failure behavior, which keeps it out of 5 territory.

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

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

Two sentences, zero filler, with the core purpose front-loaded and the return behavior stated second. Every clause earns its place.

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

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

For a one-parameter read-only tool with no output schema, the description is nearly sufficient: it names the source of truth and that each crawler gets a status. It could be slightly more explicit about the returned value shape (allowed vs blocked vs not-specified), but nothing critical is missing.

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

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

Schema description coverage is 100% with a single 'url' param whose schema note already explains 'any URL on the site'. The description adds no syntax, format, or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (check) and resource (AI crawler access via robots.txt), and names concrete crawlers (GPTBot, ClaudeBot, PerplexityBot, Google-Extended). No sibling tool overlaps with this purpose, so an agent can select it unambiguously.

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

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

Usage is implied — you call it when you want to know if AI crawlers are blocked. There is no explicit when/when-not statement, no mention of prerequisites (e.g., site must be publicly reachable), and no named alternative, though the sibling list contains no close substitute.

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 readOnlyHint, idempotentHint, and openWorldHint, so safety is covered. The description adds real substance beyond that by enumerating the signals it inspects and noting it 'Returns findings for that page', giving the agent a sense of the operation's output character.

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 verb, one dense sentence plus a brief return note, with no filler. The second sentence 'Returns findings for that page' overlaps slightly with the first, a minor redundancy that keeps it just short of perfect.

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

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

For a one-parameter read tool whose annotations cover the safety profile, the description is largely sufficient. However, with no output schema, 'Returns findings' is vague about the shape of results, and it never addresses how this differs from run_citation_check, leaving a gap in routing 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?

There is a single parameter with 100% schema description coverage ('The full page URL to check'), so the schema fully documents it. The description reinforces the single-URL scope but adds no syntax, format, or validation detail beyond what the schema provides. Baseline 3 applies.

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

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

Names a specific verb (check) and resource (a single page's citation readiness) and enumerates what it evaluates: clear answers, headings, metadata, authorship, freshness. The scope qualifier 'a single page' is precise. It does not, however, distinguish itself from the sibling run_citation_check or list_citations.

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

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

The phrase 'a single page' implies the intended granularity versus a broader check, but there is no explicit when-to-use statement, no exclusion of alternatives, and no mention of the sibling run_citation_check. Usage is left to inference.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false. The description adds valuable context beyond them: nothing is written or charged until approval, i.e., a low-cost draft stage. It does not address the non-idempotent hint (repeat calls create new briefs), leaving one gap.

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

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

Two tight sentences with zero waste. The core purpose is front-loaded, followed by the approval workflow and the key default behavior.

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 no explanation, and the draft/approval workflow is well covered. Yet for an 8-parameter tool with no schema descriptions, the near-total absence of parameter semantics (tone, topic, intent, audience) leaves meaningful gaps.

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

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

With 8 parameters and 0% schema description coverage, the description must compensate, but it only explains tracked_domain_id (defaulting to the workspace's first tracked domain). The other seven parameters (tone, topic, intent, audience, language, target_queries) are left entirely undocumented.

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: 'Create a draft brief for an article.' The word 'draft' cleanly distinguishes this from approve_brief and update_brief siblings. However, it does not explicitly contrast itself against update_brief or get_brief.

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 embeds the workflow by naming approve_brief as the required next step ('until the brief is approved with approve_brief'), which implies when to call this. But there is no explicit 'use this when' statement nor guidance versus update_brief for modifying an existing brief.

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

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

Goes well beyond the annotations (which only say not read-only, not destructive, open-world, not idempotent) by disclosing that nothing is charged by the call, that payment happens in the browser, that an existing active plan redirects to the billing page, and that the idempotency_key should be unique and reused on retry. This is exactly the extra behavioral context structured fields cannot convey.

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

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

Four front-loaded sentences that each carry distinct information (what it does, no charge, active-plan redirect, agency exclusion, idempotency guidance). Minor slack in phrasing such as 'and give it to the person' but no real waste.

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

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

For a 2-param mutation with an output schema already covering return values, the description supplies the key scenarios (new purchase, existing-plan change, agency path) and the retry/idempotency contract. Nothing an agent needs 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?

Schema description coverage is 0%, so the description must compensate. It enumerates the plan values and, more importantly, explains idempotency_key semantics (send a unique key and reuse it on a retry), which the schema only constrains by length. Good compensation, though the plan param is not elaborated beyond the enum already present.

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

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

States a specific verb (create) and resource (Stripe Checkout link) with clear scope (self-serve Rankwise plan: starter/growth/scale). An agent can distinguish it from siblings like get_plan_and_credits or get_free_ai_audit_link without opening the schema.

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

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

Gives clear when-to-use context (self-serve plans for this workspace's account) and an explicit exclusion (agency plans are handled by the Rankwise team), plus the alternate path when an active plan exists. It stops short of naming a specific sibling tool as the alternative, so not a 5.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=true, so the safety profile is covered. The description adds genuinely new context: the removal is reversible, the restore path is the Rankwise app Demand page, and 'Nothing is deleted' reinforces non-destructiveness. It omits permissions or any effect on downstream reports, so it falls short of a 5.

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

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

Three short sentences, front-loaded with the action and scope, then the recovery path and the reassurance. Every sentence earns its place 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?

With annotations covering the safety profile and an output schema present, the description need not explain return values, and it supplies the one thing structured data cannot: reversibility and the restore location. The only shortfall is the undocumented parameter.

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

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

Schema description coverage is 0% and the description never mentions opportunity_id or its UUID format, so it adds nothing beyond the bare property name in the schema. The single parameter is obvious in intent but undocumented in both places, which is a real gap.

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

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

The description gives a specific verb and resource ('Remove one topic from the workspace's opportunity queue'), which is clearly distinct from read-oriented siblings like list_opportunities or refresh_opportunities. It does not explicitly name those siblings, so an agent must infer the contrast, but the scope phrase 'one topic' makes the action 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?

Usage is only implied: an agent can infer 'dismiss' means pulling a topic out of the queue, and the restoration note hints at the reversible workflow. There is no explicit statement of when to dismiss versus archive/ignore, and no preconditions or 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?

Discloses far more than the annotations: exact credit cost per length tier, background/async execution, that output is not published, the Autopilot-equivalent content properties (real sources, only existing links, CTA, Article+FAQ schema), and idempotency_key retry behavior. Annotations only cover readOnly=false and openWorld=true, so this description carries the behavioral burden well.

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?

What the tool does is front-loaded in the first sentence; credits, async execution, the publish handoff, and idempotency each get exactly one purposeful clause with 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 7-parameter, credit-spending, async generation tool with an output schema, the description covers cost, execution model, non-publication, downstream step, and retry safety. Return-value details are correctly 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 coverage is 57%, and the description compensates for the gaps that matter: it maps each length enum value to its credit cost (1/2/3/4) and explains idempotency_key semantics ('Retries with the same idempotency_key never spend twice'). It says nothing about tone, language, or integration_id, leaving some parameters to 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?

States a specific verb+resource ('Write a new AI article for a keyword') and immediately positions it against siblings: generation is distinct from publish_article ('The article is generated in the background and is NOT published'). An agent can separate this from publish_article, replace_article, and get_article without opening a schema.

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

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

Gives a concrete precondition ('check get_plan_and_credits first') and an explicit next-step alternative ('call publish_article for that'). It does not, however, address the modify-existing path (replace_article) or other when-not conditions, so it falls just short of fully explicit routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the body is truncated to the first 4,000 characters by default, and include_html switches to the full HTML body. It does not mention pagination or rate limits, but the truncation semantics are the important disclosure here.

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

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

Two sentences, front-loaded with the resource and its returned contents, then a short pointer to the sibling for id lookup. The long enumeration of return fields is dense but each item earns its place by telling the agent what it can extract from a single call.

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

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

Although an output schema exists (so return values needn't be spelled out), the description still gives a useful preview of payload contents plus the truncation rule, and it covers the id-sourcing prerequisite. 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 50% – include_html is documented in the schema, while article_id is not. The description compensates by explaining what include_html changes (excerpt vs. full HTML) and by directing the agent to list_articles for the id, so both parameters have usable meaning even though the id's format is only conveyed by the schema's uuid pattern.

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

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

The description names a specific verb (read) and resource (one article in this workspace) and enumerates exactly what is returned: metadata, status, meta description, text excerpt, cited sources, and JSON-LD structured data. It also names the sibling list_articles as the discovery path, so an agent can distinguish it from list tools without opening a schema.

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

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

It explicitly routes the agent to list_articles to obtain the required article_id, which is the key prerequisite for invoking this tool. It does not state when to prefer a different retrieval path (e.g. search_rankwise_content) or any exclusions, so it stops short of a full when/when-not treatment.

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, idempotent, and non-destructive, so the safety profile is covered. The description adds context by enumerating returned fields, but since an output schema exists, this is somewhat redundant. It does not disclose additional traits like rate limits or auth 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 a single, well-structured sentence that front-loads the purpose and then lists the key returned fields. Every part earns its place by informing the agent of what to expect.

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

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

For a simple zero-parameter read tool with annotations and an output schema, the description provides sufficient context by summarizing the returned data. Nothing critical 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 tool takes zero parameters, so the baseline is 4. The description does not need to explain parameters, and the schema is empty, so no gaps exist.

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 'Show' and resource 'workspace's content autopilot' and enumerates the returned fields. It doesn't explicitly differentiate from the sibling set_autopilot, but the read-only intent is clear from 'Show'.

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

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

The description provides no guidance on when to use this tool versus alternatives. It only lists what the tool returns; there is no mention of calling it before set_autopilot or any other contextual usage instruction.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds the returned field inventory, which is useful context. It does not address behavior on a missing/invalid brief_id, so it adds moderate value over annotations.

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

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

A single front-loaded sentence with no filler; the verb+resource lead and the field list follows compactly. Every clause earns its place.

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

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

An output schema exists, so return values need not be re-explained, and annotations carry the safety profile. For a one-param read tool this is nearly sufficient; only the brief_id semantics and missing-record behavior are gaps.

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

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

Schema coverage is 0% and the description never mentions brief_id or its expected form, despite the schema enforcing a strict UUID pattern. The phrase 'one brief' only loosely implies identification, so the description fails to compensate for the undocumented parameter.

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

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

States a specific verb ('Read') and resource ('one brief'), and enumerates the fields returned (title, topic, intent, outline, draft article). This distinguishes it from list_briefs by scope. It does not explicitly name a sibling alternative, but the singular-entity framing is clear.

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

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

There is no when-to-use/when-not guidance and no alternatives named. An agent can infer it is the single-brief reader but gets no explicit routing (e.g., 'use list_briefs to discover brief_ids first').

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, openWorldHint, and destructiveHint=false, so safety is covered. The description still adds real value beyond that by clarifying the tool is non-executing (it fetches a link; the user runs the audit) and by summarizing what the audit itself does.

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

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

Three compact sentences, front-loaded with the core action, followed by useful context about the audit and the key non-execution caveat. No filler or redundancy.

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

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

For a one-parameter read-only tool with no output schema, the description covers what is returned in spirit (a link) and what that link does. It could be marginally more explicit that the return value is a URL string, but nothing needed 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?

Schema description coverage is 100% and the single `domain` parameter already includes an example format ('example.com'). The description mentions the domain as the audit target but adds no format, normalization, or validation detail beyond the schema, so the baseline 3 applies.

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

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

Names a specific verb and resource — 'Get the link to Rankwise's free AI visibility audit for a domain' — with a clear scope of one domain. It also separates itself from audit-executing siblings by stating 'this tool does not run the audit,' though it never names an alternative tool directly.

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

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

Gives clear usage context: the user opens the link to run the audit, and this tool itself only returns the link. That covers when this tool applies versus when the actual audit work happens, but it does not explicitly name run_citation_check or check_ai_crawler_access as the alternatives for running checks directly.

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 covered. The description adds genuinely new behavioral context beyond that: a 'paused' plan means the trial ended or the subscription was canceled, nothing is deleted, and checks/writing stay stopped until a human picks a plan at billing_url. That is real state semantics, though it doesn't cover freshness or rate limits.

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 load-bearing: what it returns, when to call it, and what the 'paused' state means. The output enumeration is front-loaded and the edge-case explanation is correctly placed last.

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 spelled out, yet the description still tells the agent what dimensions matter (plan, credits, brief cost, limits). Combined with the paused-state explanation, an agent has everything needed to call this correctly before a credit-spending action.

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

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

The tool takes zero parameters, so there is no parameter semantics to document; the baseline for a 0-param tool is 4. The description's enumeration of plan-limit categories describes output rather than input, which adds no input-side meaning.

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

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

States a specific verb (Show) and enumerates exactly what is returned: billing plan, credit balance, per-brief credit cost, and plan limits (domains, questions, AI engines, monthly AI checks). This is clearly distinct from siblings like get_workspace or get_autopilot, which an agent can rule out without opening a schema.

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

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

Gives an explicit trigger condition: 'Use it before a tool that spends credits or a plan allowance,' which is exactly the decision point an agent faces. It does not name a specific alternative or state a when-not-to-use case, so it falls short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description doesn't need to restate safety. It adds real behavioral context beyond the annotations: the default window, the 120-day cap on ranges, the state enumeration, and the 'unscheduled' bucket for cards awaiting a day.

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

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

Three dense sentences, front-loaded with the core action and return payload, then the default, then the override rule and edge case. 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?

Although an output schema exists, the description still summarizes the return shape (cards per day, unscheduled group) and covers both parameters and their constraints. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 0%, so the description must carry the burden. It documents the format (YYYY-MM-DD), the 120-day-apart constraint, and the default-window semantics for both from/to, fully compensating for the missing 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?

States a specific verb ('Read') and resource ('the Content Planner') and then enumerates exactly what each returned card contains (title, keyword, article type, state, search volume/difficulty). This distinguishes it cleanly from siblings like move_planner_card and list_articles.

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?

Explains the default behavior ('defaults to the window the planner page shows') and the condition for overriding it ('pass from and to for another'). Clear context is given, but no alternative tools are named for related needs (e.g., moving cards).

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds genuine context beyond them: the score scale (0-100) and the important edge case that the composite is null when nothing has been measured yet. It does not cover freshness/staleness or whether a score must first be generated, so not a full 5.

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

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

A single dense sentence with zero filler, front-loading the action and resource before the return contents. Every clause earns its place.

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

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

With an output schema present, return shape need not be re-explained, and the description still adds the meaningful null-score semantic. The only gap is the missing routing context relative to score_ai_visibility for a tool whose value depends on knowing when a scorecard already 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?

Only one parameter, fully documented in the schema (100% coverage) including its source ('from list_domains'). The description adds no parameter-level detail, 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 ('Read') and resource ('AI Visibility Scorecard') and enumerates the payload (composite score, latest score, confidence, per-dimension recommendations). It does not, however, explicitly distinguish itself from near-siblings like score_ai_visibility (which presumably computes) or get_share_of_voice, leaving the agent to infer the boundary.

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

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

There is no explicit when-to-use guidance: nothing tells the agent when to call this versus score_ai_visibility (recompute) or get_share_of_voice. Usage is only implied by the word 'Read'.

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=true, idempotent=true, openWorld=false and non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the fixed 28-day window and the 'connected is false until connected and synced once' state flag that tells the agent a returned result may be empty for that reason.

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

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

Two short sentences with no filler. The core content (metric, window, dimensions) is front-loaded, and the connection-state caveat follows where it belongs.

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. For a zero-param read tool, the description covers scope, data returned, time window, and the connection-state caveat — everything an agent needs to call it and interpret an empty response.

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

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

With zero parameters, the baseline is 4. The description correctly adds no argument detail because there is nothing to configure, and it does not fabricate parameters.

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

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

States a specific verb and resource (read Search Console numbers), plus the window (last 28 days) and the exact data returned (clicks, impressions, best articles by clicks). It is highly concrete, though it does not name or contrast with any sibling tool, which is the only thing separating a 4 from 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?

Usage is implied by the description: an agent can infer this is the tool for a quick GSC performance overview. However, it names no alternatives, no when-not-to-use conditions, and no prerequisites for invoking it, so guidance is only implicit.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower. The description still adds genuine behavior: the snapshot contents (share of AI answers, citations, mentions, competitor leaderboard, up to 12 earlier snapshots) and the null-when-never-measured edge case.

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

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

Two sentences, front-loaded with the action and resource, then the returned contents, closing with the null case. No filler; every clause carries information.

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

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

An output schema exists so return values need not be spelled out, yet the description summarizes them anyway. With annotations covering safety and the schema covering the parameter, the definition is complete; only the sibling relationship is unaddressed.

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

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

Schema description coverage is 100% for the single domain_id parameter, including its origin ('from list_domains'). The description adds no meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Read') and resource ('a domain's latest AI Share of Voice snapshot') and enumerates what the snapshot contains. It is unclear only relative to the sibling refresh_share_of_voice, which is never named or contrasted.

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

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

Implies it is the read path for a snapshot but gives no explicit when-to-use guidance, prerequisites, or routing against refresh_share_of_voice or list_domains. The agent must infer that this is the fetch-vs-refresh counterpart.

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 covered. The description adds scoping context (connection-level permissions, workspace kind) that isn't in the annotations, though some of this overlaps with the output schema.

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

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

Two tight sentences. The returned fields are front-loaded and the relational context is saved for the closing line, so every sentence earns its place 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?

With no parameters, rich annotations, and an output schema present, the description only needs to establish purpose and scope, which it does fully. An agent has everything required to decide to call it and know what it returns.

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

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

The tool takes zero parameters, so there is nothing to disambiguate; the schema is empty and no compensation is needed. Baseline 4 applies, as the description cannot add parameter meaning where none exists.

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 (Show) and resource (the Rankwise workspace), and enumerates the concrete fields returned: name, kind, role, permissions. The closing sentence distinguishes it from the many sibling tools by explaining it is the container context all other account tools operate within.

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?

"Every other account tool works inside this one workspace" strongly implies this is the orientation/entry-point call before other tools, giving clear usage context. It stops short of an explicit instruction (e.g. 'call this first') and names no when-not or alternative, so it is not a full 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that: result ordering (newest first), the visibility/permission rule for Experts, and the enumerated status values. It does not describe pagination or total-count 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?

A single economical sentence that front-loads the verb, resource, and ordering before moving to scoping and filtering. No filler and 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 enumerating return fields is a bonus rather than a necessity, and the role-based visibility note is valuable extra context. The only real gap is pagination semantics for page/page_size, which is modest for a read-only list tool.

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

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

Schema coverage is 50% -- query and status are documented in the schema itself, while page and page_size are bare. The description's 'Filter by status or title words' merely restates the two documented params and adds no syntax, matching rules, or pagination guidance, so the undocumented half stays uncompensated.

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 ('List the articles in this workspace') plus ordering ('newest first') and the returned field set (title, status, publish status, published URL). This is clearly distinguishable from get_article (single fetch), publish_article, and bulk_replace_articles among the 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 implies usage via filtering affordances ('Filter by status or title words') and discloses the role-scoping rule ('Experts see only the drafts assigned to them'), but never states when to choose this over sibling listings like search_rankwise_content or get_article. Usage is inferable rather than explicit.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description only needs to add operational context — and it does: default ordering is newest-first and visibility is role-dependent for experts. That assignment-scoping rule is genuinely useful behavior not derivable from the annotations or schema. It stops short of pagination/limit behavior, so not a 5.

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

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

Three short sentences with the core action and ordering front-loaded, followed by filter and visibility notes. Nothing is padded; the only cost is that the role caveat is attached as a trailing clause rather than a clearly separated note.

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 shape needn't be described. For a two-parameter, zero-required read tool with annotations carrying the safety profile, the description covers purpose, ordering, filtering, and visibility adequately; only limit behavior is unaddressed.

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

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

Schema description coverage is 0% for two parameters. The description addresses status by loosely glossing the states it filters over (drafts awaiting approval, approved pieces in progress, finished), which adds semantic meaning to the enum. The limit parameter is never mentioned, so half the parameters remain unelaborated — enough for a 3, not full compensation.

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 ("List the workspace's content briefs") and adds useful scope: ordering (newest first) and the breadth of states covered (drafts, approved, finished). An agent can distinguish it from the singular get_brief by the plural list semantics, but no sibling tool is named explicitly, which keeps it at 4 rather than 5.

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

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

The description implies usage (browse the brief backlog, optionally narrow with a status filter) and adds a role-scoping caveat ("An expert sees only the briefs assigned to them"). It never states when to prefer this over siblings like get_brief or list_articles, and gives no conditions or exclusions, so this is implied guidance rather than explicit routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuine behavioral value beyond that: it discloses the edge-case rule that an engine failing to answer is skipped rather than recorded as 'not cited', and that results reflect the latest measurement rather than history.

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

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

Two tight sentences with no filler; the enumeration of returned fields comes first and the non-obvious skip behavior is front-loaded in a second, separate sentence. Nothing here is wasted.

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

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

An output schema exists, so the description correctly does not spend words explaining return values. For a simple 2-parameter read tool this is nearly complete; the only shortfall is the missing routing hint relative to run_citation_check and get_share_of_voice.

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 domain_id and limit are already documented in the schema, including the 'from list_domains' provenance and the 1-500 bound. The description adds nothing about parameter tuning (e.g., what limit does to pagination of questions/engines), 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 ('show') and resource (latest citation measurement per tracked question and AI engine) and even enumerates the returned fields: cited status, position, URLs, timestamp. It is clear what the tool does, but it never names the sibling that would trigger a fresh measurement (run_citation_check), so the boundary is inferable rather than explicit.

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

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

The phrase 'latest real measurement' implies this is the read-only reporting path rather than a trigger, which is the right usage context. However, there is no explicit statement of when to call this versus run_citation_check or check_citation_readiness, and no prerequisites 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 this as a read-only, idempotent, non-destructive, closed-world operation, so the safety profile is covered. The description adds genuine behavioral context beyond that: the score range (0-100) and the null-when-unscored edge case, which tells the agent to expect missing values.

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

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

Two sentences, front-loaded with the action and scope, with the chaining hint at the end. The long enumeration of returned fields is somewhat redundant given an output schema exists, but it remains readable and each item is meaningful.

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 zero-parameter, read-only list tool with a full output schema and complete annotations, the description covers what an agent needs to select and invoke it. The field enumeration duplicates the output schema, so it adds little, but nothing essential is missing.

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

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

The tool takes no parameters, so the baseline of 4 applies. The description correctly does not invent parameter semantics, and the id reference points to fields returned rather than inputs.

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

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

The description states a specific verb+resource ('List the domains this workspace tracks for AI visibility') and scopes it clearly to the workspace. It stops short of differentiating from adjacent siblings like list_sites, so an agent must infer whether 'domains' and 'sites' are the same concept.

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 closing sentence 'Use the id with the other domain tools' implies a chaining workflow (call this first, then use the id with add_domain/remove_domain/recrawl_domain). However, there are no explicit when-to-use vs when-not conditions and no named alternatives, so guidance is only implied.

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

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

Annotations already cover readOnlyHint, idempotentHint and destructiveHint, so the safety profile is settled. The description adds genuinely new context: fixes are proposals only, Rankwise does not modify the site, and the user or their developer must apply them — which sets correct expectations about side effects. It does not mention pagination or volume of results, which keeps it from a 5.

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

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

Two sentences, front-loaded with the verb and resource, then the per-fix detail, then the no-side-effects caveat. Every clause carries information; nothing is padding.

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

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

For a read-only single-parameter list tool with a full output schema, the description is nearly sufficient, and it helpfully summarizes the returned fields (page pattern, dimension, rationale, status) even though the output schema exists. The one real gap is routing versus preview_fixes, which leaves an obvious ambiguity unresolved.

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

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

There is a single parameter and schema description coverage is 100%, with the schema itself stating it comes from list_domains. The description adds no format or source detail beyond that, so the baseline 3 for schema-covered parameters applies.

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

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

Names a specific verb and resource ('List the on-page fixes Rankwise proposes for a domain') and enumerates the fix categories (structured data, head tags, robots rules), so the agent knows the content type precisely. It also previews the per-fix payload. It stops short of a 5 because it never distinguishes itself from the sibling preview_fixes, which an agent could easily confuse with this 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?

There is no when-to-use or when-not-to-use statement, and no alternative is named despite preview_fixes and list_opportunities being plausible neighbors. The sentence about Rankwise not changing the site describes behavior, not tool selection. Usage must be inferred entirely from the tool name.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful nuance ("one per card", "when measured") about what is returned, but says nothing about pagination, result caps, or ordering for a list operation.

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

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

Two sentences, front-loaded with the verb and resource, and the field list is packed efficiently. The trailing CSV sentence is slightly out of place for an MCP tool description (it points at an HTTP endpoint), but it is short and potentially 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?

An output schema exists, so return values need not be re-explained, and annotations carry the safety profile; the description is nonetheless sufficient for a simple single-parameter list tool. Only pagination/limit behavior is left unstated, which is 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?

There is a single optional parameter and schema description coverage is 100%, with the enum values fully enumerated in the schema. "Filter by state" in the description adds no syntax or semantics beyond what the schema already provides, so the baseline of 3 applies.

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

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

States a specific verb (List) and resource (keywords in the Content Planner) and even enumerates the returned fields, so the agent knows exactly what comes back. It scopes to the Content Planner, which separates it from generic listers, but it never names a sibling tool (e.g. list_articles, list_questions) to disambiguate.

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?

"Filter by state" implies the filtering use case, and the CSV sentence gives a when-to-use alternative — but the alternative is a raw REST endpoint, not a sibling MCP tool, so it doesn't help the agent choose between list_keywords and list_articles/list_questions. No exclusions or prerequisites are stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: dismissed topics are filtered out, results are ranked/scored on three named dimensions, and each row carries a covered/not-covered flag. It stops short of describing ordering or pagination.

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

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

Three compact sentences with no filler, front-loaded with the core identity of the resource before the scoring/exclusion details. Slightly dense in the middle sentence, but every clause earns its place.

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

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

An output schema exists, so return values needn't be spelled out, and annotations handle safety. What's present (definition, ranking basis, exclusion rule, coverage flag) is enough to call the tool, though the limit parameter and result ordering remain unaddressed.

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

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

Schema description coverage is 0% for the single 'limit' parameter, so the description carries the burden of explaining it — and it says nothing about limit, defaulting, or the 1-100 range. With low coverage the description should compensate, and here it does not.

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

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

It names a specific verb and resource ('list... content opportunities') and goes further by defining what an opportunity actually is: 'topics where AI engines answer questions the brand is not cited for.' The scoring dimensions (demand, citation gap, feasibility) and the coverage note make it trivially distinguishable from siblings like dismiss_opportunity or refresh_opportunities.

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

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

Usage is only implied by the verb 'list'. It never says when to reach for this versus refresh_opportunities (to regenerate results) or how it relates to dismiss_opportunity beyond noting dismissed topics are excluded. Adequate context, but no explicit when/when-not routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety behavior is covered. The description adds useful context beyond annotations by disclosing that each question includes its latest check result status (cited, not_cited, error), citation position, and run time, though it does not discuss pagination or ordering.

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

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

The definition is a single well-structured sentence that front-loads the action and resource, then concisely lists the returned information. There is no redundant or filler text.

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

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

Given the low complexity (one required parameter), full schema coverage, annotations covering safety, and an existing output schema, the description provides enough context for an agent to understand the tool's purpose and expected return contents. No material gaps remain.

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

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

There is one parameter with 100% schema description coverage, and the schema already explains domain_id as 'The tracked domain's id, from list_domains.' The description says results are for 'a domain' but adds no further parameter semantics beyond what the schema provides, so 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 uses a specific verb and resource: 'List the questions tracked for a domain,' and clarifies that these are the prompts Rankwise asks AI engines. It also enumerates the returned fields, making it clearly distinguishable from siblings like add_question, remove_question, and list_domains.

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

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

The description implies the tool is used to retrieve tracked questions for a specific domain, but it does not explicitly state when to use this versus alternatives like list_citations or run_citation_check. It gives clear context without exclusions, leaving routing largely implicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered. The description adds only that the sitemaps are 'exposed by Rankwise' for enumerating indexable content, without disclosing return structure or whether sitemaps are global vs per-site. With annotations carrying the behavioral burden, a 3 is fitting.

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

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

A single front-loaded sentence with zero waste. The verb-first structure makes the tool's action immediately legible.

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 zero-parameter, read-only listing tool with rich annotations and no output schema, the description provides enough to call it correctly. A minor gap is whether the returned sitemaps are workspace-scoped or site-specific, but overall it is sufficiently complete.

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

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

The schema has zero parameters, so the parameter_semantics baseline is 4. There is nothing for the description to clarify about inputs, and it correctly implies a no-argument listing call.

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?

Uses a specific verb (List) and resource (sitemap URLs) scoped to Rankwise, so an agent knows what to expect. However it does not differentiate from related siblings like list_sites, list_domains, or search_rankwise_content, leaving a small ambiguity about how this differs from other listing 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 clause 'so agents can enumerate indexable content' implies the use case (discovering indexable URLs), which is useful. But there is no explicit when-to-use/when-not guidance and no reference to alternatives like search_rankwise_content for content enumeration.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the connection-to-site cardinality model and what state is surfaced (autopilot on/off, weekly volume, paused), which is context beyond the structured fields, but says nothing about errors or edge cases when no site is 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?

Two tight sentences, front-loaded with the scope-defining clause before the detail list. Slight redundancy in re-enumerating return fields that an output schema already documents, but it reads as a useful scan-level summary rather than padding.

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

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

With zero parameters, an output schema covering return values, and annotations covering the safety profile, the description only needs to add scope semantics — and it does, explaining the one-site-per-connection model that no structured field captures. Nothing needed to call this 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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. It correctly adds no parameter discussion, keeping the description focused on scope rather than inputs.

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

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

States a specific verb (list) and resource (the site this connection reaches) and enumerates what comes back: id/workspace id, name, tracked domains, autopilot state, cadence, and paused flag. It is clearly distinguishable from list_domains/list_articles by being singular and connection-scoped, though it never names a sibling tool explicitly.

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

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

The second sentence supplies real usage context: a connection reaches exactly one site, so this tool is not for enumerating multiple sites, and getting another requires reconnecting or adding a CLI profile. That is an implicit exclusion plus a workaround, but there is no explicit routing to an alternative tool for multi-site cases.

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 safety is covered; the description adds genuinely new behavioral context by stating the sort order ('newest first') and the content of the feed. It does not mention pagination behavior or what happens when the result set exceeds the page size, which is the remaining gap.

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

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

One sentence, front-loaded with the resource and the ordering guarantee, followed by the filters. Adjacent clauses carry the event taxonomy without padding; every clause adds information an agent would otherwise have to infer.

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

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

With an output schema present, return values need not be described, and the annotations cover the read-only safety profile. The description supplies ordering and filter semantics, leaving only minor gaps (limit/pagination, whether an empty feed is possible) for what is a simple three-parameter read tool.

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

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

Schema description coverage is 67%: since and domain_id are documented in the schema (including 'from list_domains' provenance), while limit has only bounds and a default. The description restates the two filters at a high level but adds no detail beyond the schema and says nothing about limit, so it neither compensates for the gap nor detracts.

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?

Names a specific verb (list) and resource (recent AI visibility events) and enumerates the event types included (citations won/lost, fixes proposed, goals reached), which lets an agent distinguish this aggregate feed from narrower siblings. It stops short of explicitly contrasting itself with list_citations or list_fixes, whose subject matter overlaps with two of the enumerated event types.

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?

'Optionally only since a date or for one domain' tells the agent what filtering is possible but not when to choose this feed over siblings such as list_citations, list_fixes, or score_ai_visibility. Usage is implied by the resource name rather than stated, and no exclusions or prerequisites 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 readOnly=false, idempotent=true, destructive=false, openWorld=false, so safety is covered. The description adds real behavioral context beyond them: collision behavior (the two cards swap), refusal semantics for occupied days, and the fact that the operation costs nothing ('Free'). Return format is not described, but an output schema 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?

Four short sentences, front-loaded with the action, then collision, then refusal, then cost. Efficient, though the trailing one-word 'Free.' is telegraphic and slightly unclear in isolation.

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 needn't be explained, and the description covers the mutation's preconditions, collision resolution, and cost. What remains thin is parameter-level meaning (which day format, which card_id), the only real gap for correct invocation.

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

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

Schema description coverage is 0% and the description never explains card_id or day. It implies day is a publishing date, but the card_id semantics and what 'not written yet' means for the identifier are left entirely to the schema's patterns/formats, which do not compensate for the coverage gap.

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

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

States a specific verb (Move) and resource (planner card) plus the scope constraint that only unwritten cards can be moved. An agent can distinguish this from sibling tools like get_planner or replace_article without opening the schema.

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

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

Explicit preconditions: the card must not be written yet, and the target day must not be held by an article in progress or published. It doesn't name alternative tools, but no sibling performs this operation, so the conditions are the useful guidance.

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

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

Annotations already cover safety (destructiveHint=false, idempotentHint=true, readOnlyHint=false), so the bar is lower. The description adds real behavioral context beyond them: what is suspended (planner fill, drafting, publishing), that no credits are consumed, and that manual actions remain available — a useful disclosure for a mutation tool. It doesn't mention permissions or whether already-scheduled items are affected.

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

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

Four short sentences, zero filler, with the effect stated first and the escape hatch (resume_site) last. Every clause conveys distinct information.

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

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

With an output schema present, return values need no explanation, and the description covers the operational impact thoroughly. Minor gap: it doesn't say whether pausing affects already-queued or in-flight jobs, which matters for a state-changing tool.

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

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

Schema coverage is 100% and the single optional site_id already documents the default-to-connection-site behavior. The description references 'the site' at a scope level matching the parameter but adds no format or selection detail, so the baseline 3 is appropriate.

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

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

States a specific verb+resource ('Pause automatic articles for the site') that is unambiguously distinct from siblings like pause-related state changes. An agent immediately knows this halts automation rather than editing content.

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

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

Names the counterpart tool explicitly ('Resume with resume_site') so the agent knows the reverse operation exists. Scope guidance is present ('While paused nothing runs on its own... Manual actions still work'), though it never states the trigger condition such as a user asking to stop automation or avoid credit spend.

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, and the 'changes nothing' phrasing largely restates that safety profile. It does add useful context that it reads live pages and returns a diff, but discloses nothing about auth needs, rate limits, or limits on the preview.

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

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

Two short sentences, front-loaded with the core purpose and immediately followed by the dry-run constraint. No filler or redundancy.

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

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

An output schema exists, so the return format need not be re-explained, and annotations cover the safety profile. What remains is a complete picture of a read-only preview for a one-parameter tool, with only 'when to use vs list_fixes' left implicit.

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

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

Schema description coverage is 100% and the single domain_id parameter is fully documented in the schema (including a pointer to list_domains). The description adds no parameter-level meaning, so the baseline 3 is appropriate.

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

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

States a specific verb (show) and resource (the change each proposed fix would make to the domain's pages) plus the output form (before/after diff). This clearly distinguishes it from the sibling list_fixes, though it never names that sibling explicitly.

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

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

'A dry run: it reads the live pages and changes nothing' implies it is the safe preview step taken before committing fixes, but the description never states when to pick this over list_fixes or what the apply/next step is. Usage is only implied.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and readOnlyHint=false, so the safety profile is covered. The description adds valuable impact context beyond that: publishing makes the article live on the customer's public website, and a draft must be expert-approved first. It stops short of saying whether a publish can be undone or what happens on partial CMS failure.

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 front-loaded sentences, each carrying distinct information: purpose/destinations, external impact, prerequisite, then parameter usage. No filler or restatement of the title.

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

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

An output schema exists so return values needn't be explained, and annotations cover the safety profile. The main remaining gap is the unexplained idempotency_key, plus no statement about failure/retry behavior for a destructive, non-idempotent operation.

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

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

Schema description coverage is 0%, so the description has to carry the load. It explains publish_at (ISO date-time or 'next_slot') and the conditional use of integration_id well, and implies article_id. The required idempotency_key is never mentioned, leaving one of four parameters undocumented anywhere.

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 ('Publish one article') and enumerates the concrete destination set (WordPress, Shopify, Webflow, etc.), which distinguishes it from siblings like generate_article and approve_brief. An agent knows exactly what this tool does without opening the schema.

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

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

Gives a real prerequisite ('A brief draft must be approved by its expert first') and conditional routing rules for integration_id and publish_at. It does not, however, name the alternative tools an agent might reach for (e.g., generate_article to produce the draft), so the guidance has context but no exclusions.

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

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

Goes beyond annotations by disclosing that execution is background/async, takes 'a few minutes,' and consumes no credits. These are exactly the behavioral facts an agent needs and that readOnlyHint=false / idempotentHint=true alone do not convey. It stops short of noting rate limits or whether overlapping calls are coalesced.

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

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

Three short sentences, zero filler. The core action is front-loaded, followed by execution characteristics and the cost caveat. Every clause earns its place.

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

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

For a background mutation with a rich schema and an output schema already covering return values, the description supplies everything else the agent needs: async nature, latency expectation, follow-up step, and cost. Nothing material is missing.

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

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

Schema description coverage is 100%, and the domain_id field already documents its source ('from list_domains'), so the schema carries the semantics. The description adds nothing about the single parameter, which matches the baseline-3 expectation when the schema does the work.

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: 'Queue a fresh crawl and re-score of a tracked domain's pages.' This cleanly distinguishes it from add_domain, remove_domain, list_domains, and get_scorecard among siblings. An agent immediately knows this triggers a recomputation rather than a lookup.

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

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

Gives clear operational context: it is asynchronous ('runs in the background') and directs the agent to the follow-up tool ('read get_scorecard afterwards'). It lacks an explicit when-not or a statement of prerequisites beyond having a domain_id, so it falls short of the full when/when-not/alternatives pattern.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true and idempotentHint=false, and the description adds real context beyond them: paid-data consumption, a 10-minute per-workspace throttle, and idempotency-key retry semantics. The one material gap is what happens to the existing queue/dismissed opportunities on recompute — with destructiveHint=false an agent still cannot tell whether prior state is preserved or replaced.

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

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

Two sentences, no filler, and the information is front-loaded: what it recomputes first, then the cost/rate constraint, then the idempotency instruction. Every clause carries a distinct, actionable fact.

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 no explanation, and the description covers cost, throttle and retry behavior for this single-parameter tool. The remaining hole is the state-transition question (does recomputation replace or merge with existing opportunities, and what happens to dismissed ones) plus auth requirements, which for a write-flagged tool is a meaningful omission.

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

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

Schema coverage is 0% (the idempotency_key property carries only min/max length), so the description must carry the meaning, and it does: a unique key per call, reused on retry. It does not restate the 8–200 character format constraint, but the key's purpose and lifecycle — the part an agent actually needs — are supplied.

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

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

The description names a specific verb and resource ('Recompute the workspace's opportunity queue') and explains the inputs it derives from ('tracked questions and AI citation data') plus the downstream effect ('look for new topics'). It is clearly distinguishable from the read-oriented siblings list_opportunities/list_questions in kind, but it never names or contrasts any sibling explicitly, so it stops just short of the top band.

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 genuine operational guidance — the call consumes paid search/AI data and is limited to once per 10 minutes per workspace, and retries must reuse the same key. What it does not give is when to reach for this tool versus list_opportunities (read the current queue) or refresh_share_of_voice (a different recompute), leaving the selection decision to inference.

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

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

Annotations declare only the coarse profile (not read-only, open-world, not idempotent, non-destructive). The description adds substantive behavior the annotations cannot convey: a cached snapshot from the last 12 hours is returned rather than paying for a new one, the reason is index lag, and retries must reuse the same idempotency_key. That is exactly the credit-spend and dedup context 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?

Three short sentences, front-loaded with the action and the surprising caching rule. Every sentence carries information an agent would otherwise have to guess; there is no filler.

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

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

With an output schema present, return values need not be described, and the mutation's cost/caching semantics are covered. The only gap is the missing explicit contrast with get_share_of_voice, which would complete the routing picture.

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 50%: domain_id is documented in-schema (including its list_domains provenance), but idempotency_key has only length bounds. The description compensates by explaining that the key must be unique and reused on retry, which is the essential semantic for that undocumented parameter.

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

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

Names a specific verb (capture a fresh snapshot) and resource (AI Share of Voice) plus the upstream source (DataForSEO LLM Mentions), so the agent knows exactly what the call produces. It does not explicitly distinguish itself from the sibling get_share_of_voice, leaving the read-vs-refresh distinction to inference.

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

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

The 12-hour cache rule gives implicit guidance on when a call is cheap versus costly, and the retry instruction is explicit. However, there is no direct when-to-use-this vs get_share_of_voice guidance, which is the most likely confusion given the sibling tool.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is partly covered. The description adds genuinely new information: the cascading scope (questions, AI answers, scores, history are also deleted) and explicit irreversibility ('This cannot be undone'). It does not mention idempotency or error behavior, keeping it short of a 5.

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

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

Two tight sentences with zero waste; the scope of deletion is front-loaded and the irreversibility warning follows immediately. Nothing is redundant with the title or annotations.

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

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

For a one-parameter destructive tool with an output schema present and annotations declaring the safety profile, the description covers everything an agent needs: the affected resource, the cascade of data removed, and the fact that the action is irreversible.

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 single parameter, domain_id, is fully documented in the schema itself (including format, pattern, and provenance from list_domains). The description adds no format or sourcing detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb+resource combination ('Stop tracking a domain and permanently delete') and enumerates the deletion scope (questions, AI answers, scores, history). An agent can immediately distinguish it from siblings like remove_question, add_domain, or list_domains.

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

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

The use case is implied — remove a tracked domain — but there is no explicit when-to-use vs when-not guidance and no alternative named (e.g., a way to stop tracking without deleting). Usage is inferable but nothing routes the agent explicitly.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the bar is lower, yet the description still adds value: it specifies what is destroyed ('delete its check history') and that the action is irreversible ('This cannot be undone'). It does not mention auth or permission requirements, keeping it short of a 5.

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

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

Two sentences, zero filler, with the destructive consequence and irreversibility front-loaded. Every clause earns its place.

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

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

An output schema exists, so return values need not be described, and the annotations cover the safety profile. The description fills the key remaining gap (irreversibility and what data is lost), though it omits any mention of prerequisites or downstream effects on the workspace.

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

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

Schema description coverage is 0% for the single question_id parameter, so the description technically carries the burden but adds no meaning about which question or how it is identified. The parameter is self-evident from its name and format, so this is a minor gap rather than a serious one.

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 ('Stop tracking a question') and scopes the effect ('delete its check history'). An agent can distinguish this from list_questions or add_question 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?

No when-to-use guidance and no alternatives named. For a removal tool sitting next to siblings like archive_brief or remove_domain, the description never says when removal is appropriate versus simply stopping tracking or leaving the question alone.

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

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

Despite annotations already declaring destructiveHint=true and idempotentHint=true, the description adds substantial non-obvious behavior: slug uniqueness scoping, that open tracked changes are silently dropped when the body changes, that a published article's live post is unaffected until republished, and pricing ("Free"). These are exactly the caveats an agent cannot derive from 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?

Five sentences, front-loaded with the action and scope, then escalating to the constraints that matter most (uniqueness, destructive tracked-change loss, publish caveat). Every sentence carries distinct information, though the trailing "Free." fragment is an orphaned addendum.

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 no explanation, and the destructive/idempotent profile is covered by annotations plus the in-description caveats. Nothing an agent needs to invoke this correctly, including the surprising side effects, 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 only 20%, so the description must carry weight. It names the four mutable fields (title, meta_description, slug, html), and adds the slug-uniqueness constraint, which the schema does not encode. It stops short of per-field format guidance that the low coverage would ideally require.

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 (replace) and resource (article) and enumerates exactly which fields are replaceable (title, meta description, slug, HTML body). This clearly scopes the tool apart from get_article, publish_article, and bulk_replace_articles.

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?

"Send only the fields to change" gives an implied partial-update usage pattern, and warning that re-publishing is needed gives actionable follow-up. However, it never states when to use this vs bulk_replace_articles or when not to use it, leaving the alternative-selection question to inference.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: cards from past days are re-queued to the next free publishing days, and resuming incurs no cost. It still doesn't mention auth/permission needs or return format.

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

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

Three short sentences, no waste, with the core action and its precondition front-loaded before the scheduling and cost 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?

For a single-parameter, non-destructive, idempotent mutation with an output schema and full annotation coverage, the description supplies everything an agent needs: the action, when it applies, its scheduling consequence, and its cost.

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 site_id as coming from list_sites with a connection default. The description adds no parameter detail, 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 ("Resume") and resource ("automatic articles for the site"), with the precondition "after a pause" making it immediately distinguishable from the sibling pause_site. An agent can identify the operation without opening the schema.

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

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

The phrase "after a pause" gives clear context for when to call it (only relevant to a site that was paused), and the scheduling sentence clarifies the effect. It does not explicitly name pause_site or state when-not to use it, so it stops short of a full 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 only supply the safety profile (readOnly=false, destructive=false, openWorld=true); the description adds substantive behavior: recent engines are served from cache at no cost, the call consumes a monthly allowance, and retries must reuse the same idempotency_key. These cost and caching semantics are exactly the context an agent needs before invoking.

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 tightly packed sentences, purpose front-loaded, then caching, cost, and idempotency guidance in descending order of importance. No filler or repetition of the title.

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

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

An output schema exists so return values need not be described, and annotations cover the safety profile. The description covers caching, allowance, and retry handling, but omits edge behavior such as what happens when the monthly allowance is exhausted, which is relevant for an open-world, quota-consuming 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 description coverage is 0%, so the description must carry the load. It explains idempotency_key usage well (unique value, same value on retry) but says nothing about question_id beyond the implicit 'one tracked question', leaving the UUID requirement undocumented in both places.

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

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

States a specific verb and resource ('Ask the plan's AI engines one tracked question now and record whether each cites the brand'). The 'now' / on-demand framing cleanly separates it from passive sibling reads like list_citations or list_visibility_events.

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?

Conveys the operating context (on-demand check for a tracked question, cached results reused, allowance consumed), which implies when it is appropriate. However it never names an alternative (e.g. list_citations for existing results) or states when not to use it, so routing is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds substantial non-obvious behavior: the shape of the result (score, issues, quick wins), the anonymous-call side effect of minting a claim link, what that link unlocks (a workspace pre-loaded with the domain and a started trial), its single-use constraint and 72-hour expiry. None of this is derivable from the schema or annotations.

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

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

Front-loads what the tool does and what it returns before the caveat and the claim-link mechanics. Every sentence earns its place: the negative scope prevents misuse, and the claim-link sentences cover behavior an agent cannot infer elsewhere.

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

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

There is no output schema, and the description compensates by naming the return payload (score, issues, quick wins). Combined with the explicit scope caveat and the full claim-link lifecycle, an agent has everything needed to call this correctly and to explain the result to a user.

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

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

With one parameter at 100% schema description coverage ('The domain to score, e.g. example.com'), the schema already carries the meaning and the description adds nothing about domain format, subdomain handling, or whether protocol/path is accepted. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (score), a specific resource (a website's homepage readiness for AI search engines), and enumerates the three dimensions checked (crawler access, structured data, content signals). It also draws an explicit boundary that no sibling draws: 'an on-page readiness check, not a measurement of real AI citations,' which separates it from run_citation_check, list_citations and check_citation_readiness.

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 negative scoping ('not a measurement of real AI citations') gives clear context for when this tool is the right choice versus citation-measurement tools. It also documents the unsigned/claim-link flow for anonymous callers. It never names a concrete sibling to use instead (e.g. check_citation_readiness for the narrower access check), so routing is implied rather than explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds value beyond that by disclosing the indexed corpus and the return shape ('matching titles with canonical URLs'), though it says nothing about result ordering or paging 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?

Two sentences, front-loaded with the verb+resource and then the corpus list. The enumeration of content types is long but each item earns its place by clarifying search scope; nothing is 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?

With no output schema, the description correctly takes on the return-value burden by stating that matching titles and canonical URLs come back. For a read-only, two-parameter search tool with full annotation coverage, that is sufficient — only pagination/ordering semantics are unaddressed.

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

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

Schema coverage is 100% — both 'query' (free-text matched against titles, descriptions, topics) and 'limit' (1-25, default 10) are fully documented in the schema. The description adds no syntax or matching-behavior detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb (Search) and resource (Rankwise's public library), then enumerates exactly what's indexed: guides, glossary terms, comparisons, free tools, AI crawler directory, AI engine pages. This clearly distinguishes it from the workspace-scoped siblings (list_articles, list_briefs, list_keywords), which operate on user data rather than the public library.

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

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

Usage is implied by the word 'public library' — an agent can infer this is for discovering Rankwise-hosted reference content rather than the user's own workspace items. However, it never explicitly states when to reach for this versus a sibling like list_rankwise_sitemaps, nor does it set any exclusions.

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

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

Annotations only cover safety hints (readOnly false, idempotent true), so the description carries the real burden and delivers: it discloses that one mode spends credits, that weekly_quota is plan-capped, and that auto-publishing is refused here with a redirect to the app. These are exactly the side-effect details an agent needs before invoking a settings mutation.

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

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

Leads with the purpose, then spends two dense sentences on mode semantics; every clause carries decision-relevant information. The mode enumeration is compact but the parenthetical explanations make the second sentence heavy.

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

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

Output schema exists so return values need no explanation, and the description covers the costly/irreversible aspects plus the unsupported mode. It does not state that omitted parameters leave current settings unchanged (0 required params), which matters for a partial-update tool.

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

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

Schema coverage is only 33% (only mode is documented in the schema), so the description compensates by defining each mode's cost/review behavior, noting weekly_quota is plan-capped, and explaining paused toggles the scheduler. 'paused pauses or resumes' is slightly circular and the quota's 1-7 bound is left to the schema, but coverage is meaningfully improved.

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 ('Change the workspace's content autopilot'), which cleanly separates it from the read-only sibling get_autopilot. The follow-on sentences enumerate the exact modes so an agent knows the decision space before opening the schema.

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

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

Gives real selection context for each mode: draft_only 'spends nothing' versus requires_approval which spends credits and holds drafts for review, plus an explicit exclusion (full_auto cannot be set here, use the Rankwise app). It stops short of naming the sibling to call for reading current settings, so it is clear context without full alternative routing.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, idempotentHint=true, destructiveHint=true), so the bar is lower. The description adds a genuinely non-annotation detail: the state constraint that approved briefs are uneditable. It stops short of explaining partial-update semantics (whether omitted fields are preserved or cleared), which matters for a tool flagged 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?

Two sentences, nothing wasted: purpose and scope first, then the state restriction. Front-loaded 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?

An output schema exists, so return values need no explanation, and annotations cover the safety profile. The description covers purpose, scope, and the approval gate, but omits patch semantics for a 6-parameter update and gives no meaning for individual fields.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does enumerate the mutable fields, mapping 'target questions' to target_queries and naming title/topic/intent/outline. It provides no per-field semantics (array replace-vs-append behavior, length or ordering constraints), so the compensation is partial.

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 ('Edit') and resource ('a draft brief') and enumerates the editable fields (title, topic, intent, target questions, outline). The phrase 'before it is approved' cleanly separates it from siblings approve_brief, create_brief, and get_brief.

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

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

Gives an explicit precondition ('before it is approved') and an explicit when-not ('An approved brief cannot be edited'), plus a redirect ('edit its draft article in the app instead'). The redirect points outside the toolset rather than to a sibling tool, so it is clear context and exclusions without a named tool alternative.

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