Actually Asked

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld false), yet the description adds substantial context: it reads exactly one page, the URL must be on the site's domain or allowed domains, it inspects script + container with the site key, explains the last_seen_at caveat for browser-built pages, and describes the Shopify live-theme path. That is meaningful behavior beyond the annotations.

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

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

Front-loaded with the core purpose, then the two branch cases; each sentence carries information. The last_seen_at sentence is a caveat that earns its place, though the overall block is on the longer side for a two-parameter tool.

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

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

With an output schema present, the description needn't document return values, and annotations carry the safety profile. It covers both execution branches and the key caveat, so it is largely complete; the only gap is not positioning itself against the get_install_instructions sibling.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics for 'url': it must be on the site's domain or allowed domains, and it is only needed for web-site checks (not Shopify). That domain/allowed-domains constraint goes beyond the schema text.

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 ('checks') and resource ('that the widget is on a site') and details the mechanism (reads page HTML for the script and a container with the site's key). Clear purpose, but it never names the closest sibling (get_install_instructions) or otherwise differentiates itself from it, so an agent must infer the boundary.

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

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

The 'For a web site... For a Shopify store...' branching gives implicit context for choosing the right input mode, which is useful. However, there is no explicit when-to-use/when-not guidance and no mention of the alternative get_install_instructions, so the routing decision 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), and the description adds non-obvious behavior on top: the entry publishes immediately rather than being staged, the system never rewrites the merchant's text, and group/page-rule/tag options are gated by plan tier. That is real disclosure beyond the 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?

Two sentences, zero padding. The core action and its immediacy are front-loaded, followed by optional capabilities and the duplicate-check prerequisite in priority order.

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 create tool with an output schema (so return values need no explanation), the description covers the action, publication behavior, optional feature gating, and the pre-call duplicate check. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds semantics the schema lacks: which optional capabilities (group, page rule, tag, pinned) exist and the plan tier required for each. It does not add format detail beyond the schema, so it sits modestly above baseline.

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

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

The description opens with a specific verb+resource ('Adds a question and answer to a site's FAQ') and immediately distinguishes this from draft-oriented siblings by stating it is 'published at once, as the merchant's own (the system never rewrites it).' An agent can separate this from publish_faq_entries or draft_faq_suggestions without opening any schema.

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

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

It gives an explicit precondition and names the tool to run first: 'Check first that the FAQ doesn't already have the question (list_faq_entries with query).' It also encodes plan-tier gates for the optional group/page-rule/tag parameters. It stops short of stating when not to use this tool (e.g. vs. update_faq_entry or draft_faq_suggestions), so it is clear context rather than full routing guidance.

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

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

Annotations already cover safety (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true). The description adds substantive non-annotation behavior: new groups are appended at the end, default site-wide visibility, and plan-tier gating for tag/page-rule placement. It stops short of stating what the response contains or ordering side effects, but the added context is meaningful.

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

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

A single dense sentence with parenthetical asides; every clause conveys distinct information (append position, default visibility, plan tiers, follow-up tools). Front-loaded with the core action, though the parentheticals make it slightly harder to scan.

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. The description covers creation semantics, default placement, plan constraints, and next steps, which is sufficient for a 4-param creation tool. Minor gaps (e.g., interaction between tag and page_rule_id) remain but are not critical.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds plan-tier semantics to the tag and page_rule_id parameters (both Growth and up) that the schema does not state. The name parameter's meaning (the heading) is also reinforced. This goes beyond what the structured fields provide.

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

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

States a specific verb and resource ('Adds a group... a heading questions sit under') and clarifies the domain term FAQ group. It is clearly distinguishable from siblings like update_faq_group, delete_faq_group, reorder_faq_groups, and create_faq_entry.

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 visibility behavior (Everywhere rule) and the conditions under which that changes (page rule or tag, Growth and up), plus plan gating (Starter and up). It routes to follow-up tools (list_placement_suggestions, update_faq_entry) but does not explicitly state when to prefer this over create_faq_entry for content.

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, so the agent knows this is a non-destructive write. The description adds a plan-tier requirement ("Growth and up") and the downstream effect that list_placement_suggestions then proposes matching entries, which is genuinely useful. It still omits permissions/auth needs and whether the rule applies immediately.

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 first two sentences are efficient, but the trailing fragment "Growth and up. Actually Asked then suggests which entries belong there (list_placement_suggestions)." is garbled and awkwardly punctuated, obscuring the plan requirement and the related-tool pointer.

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. The description covers the rule's meaning, plan gating, and a follow-up tool, but says nothing about how this relates to update_page_rule/delete_page_rule or what a created rule permits — adequate but with clear gaps for a 3-param mutation tool.

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

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

Schema description coverage is 100%, so name, paths, and site_id are already documented. The description restates the path syntax (exact vs prefix) that the schema field description already gives, adding little new. Baseline 3 applies when the schema carries the burden.

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

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

States a specific verb+resource ("Adds a page rule") and then defines what a page rule is — a set of paths, exact or prefix-with-*. That goes well beyond the title. It hints at a related sibling (list_placement_suggestions) but does not distinguish itself from create/update/delete_page_rule.

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

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

Provides a usage constraint ("Growth and up" implies a plan gate) and explains the effect of the rule on groups and entries. However it never says when to prefer this over update_page_rule or when a rule is unnecessary, so guidance 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 destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: the deletion is permanent, contained questions are orphaned rather than deleted, and one specific group is protected. It stops short of saying whether the deletion can be undone or what errors occur.

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, and the permanence of the operation plus the exception are front-loaded. Every sentence carries information an agent needs before calling a destructive tool.

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

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

An output schema exists, so return values need no explanation, and the description covers the destructive side effects that matter most for a delete tool. Minor gaps remain around undo/restore behavior and what happens if the group_id is unknown.

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

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

Schema description coverage is 100%, with both group_id and site_id documented in the schema, so the description need not repeat them. It adds no syntax, format, or lookup guidance for either parameter, which is the expected baseline 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 and resource ('Deletes a group') and clarifies the scope of the deletion ('for good'), plus what happens to the contained questions. It implicitly distinguishes itself from remove_faq_entry by noting that questions survive, 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?

Gives real usage constraints: the 'General' group cannot be deleted, and the merchant should be consulted before deleting. That covers a when-not-to-use case and a precondition, but it names no alternative tool for callers who want a less destructive outcome.

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

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

Annotations already flag destructive=true, idempotent=false and openWorld, and the description goes further by spelling out the downstream consequences: groups revert to Everywhere and entries using the rule lose it. It also restates the irreversibility ('for good') that aligns with destructiveHint.

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 core action, then consequences, then restrictions. 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 destructive single-target mutation, the description covers side effects, protected targets, and a human-approval prerequisite; annotations cover the safety profile, the schema covers both params, and an output schema exists. 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%, so both site_id and page_rule_id are fully documented in the schema itself. The description adds no syntax or format detail for either parameter, which is the expected baseline 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 and resource (delete a page rule) plus the permanence of the action with 'for good'. Sibling tools like update_page_rule and create_page_rule are not named, but the delete scope is unambiguous from the name/description pair.

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

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

Provides concrete when-not conditions ('Everywhere, Home and FAQ page can't be deleted') and a precondition ('Ask the merchant before deleting'). It does not name an alternative tool, but the contextual guidance for this mutation is clear.

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

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

Annotations already declare destructiveHint=true and non-idempotent, but the description adds real context beyond them: deletion is permanent ('for good'), only a narrow class of questions is eligible, and human approval is expected first. This tells the agent both the consequence and the precondition guardrails.

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

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

Three short sentences, each carrying distinct information: action, eligibility constraint, approval requirement. The destructive nature is front-loaded immediately after the verb.

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-value explanation is unnecessary. For a destructive mutation, the description covers permanence, eligibility, and human-in-the-loop approval, which is everything an agent needs before invoking it.

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

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

Schema coverage is 100% with only two parameters, so the schema fully documents site_id and question_id. The description adds no syntax or format detail beyond that, making the baseline 3 the right 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?

States a specific verb and resource ('Deletes a visitor question') plus a scope qualifier ('for good'), which separates it from update_question, get_question, and list_questions without needing the schema. The eligibility sentence further pins down which questions this tool targets.

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

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

Gives explicit when-not conditions: only unanswered, email-less questions (noise/spam) qualify, while leads and answered questions are kept. It also adds a procedural guideline ('Ask the merchant before discarding'). It stops short of naming a sibling alternative to use for leads or answered questions, so 4 rather than 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?

Goes well beyond the annotations by disclosing three behavioral traits: the work is asynchronous (drafts appear 'in a few minutes'), it is rate-limited ('a few drafts an hour at most per site'), and results surface as suggested entries rather than being returned directly. Annotations only say it is non-read-only and non-idempotent.

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 with no filler, ordered by importance: what happens now, the precondition, and the result/rate characteristics. The opening 'Asks Actually Asked to draft' is slightly tangled (product name embedded) but the intent is still front-loaded.

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

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

Since an output schema exists, the description need not explain return values, and it still covers the key gaps an agent needs: precondition, asynchrony, where drafts land, and throughput limits. Nothing required to call it correctly is missing.

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

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

Schema description coverage is 100% and the only parameter (site_id) is fully documented in the schema, so baseline 3 applies. The description adds no site-scoping or format detail beyond what the schema already states.

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

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

Names a specific action (draft more FAQ entries from the site's pages) and frames it against the implicit scheduled alternative ('now, rather than at the next read'). It also points to the sibling list_faq_entries with state suggested as the way to see results, so an agent can distinguish it from read-only entry tools.

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

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

Gives an explicit when-not condition: only invoke when no suggestions are waiting, review pending ones first. It does not name the specific sibling to use for that review pass (e.g. list_questions), leaving the agent to infer the tool, so it falls 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 already declare readOnly, idempotent, non-destructive, and closed-world. The description adds genuinely new behavioral context: long pages are truncated at 20,000 characters, and file results must be cited as a file rather than linked. Those are operational details the annotations do not carry.

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

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

Three short sentences, front-loaded with what the tool returns before the truncation and citation caveats. Zero padding, though the first sentence's grammar is slightly tangled.

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 structure needn't be explained. Combined with annotations covering the safety profile, the description supplies the remaining essentials: id provenance, truncation limit, and the file-citation rule. A minor omission is pagination behavior on truncated pages.

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

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

Schema coverage is 100%, and the schema already documents both document_id (from search_site_content) and site_id (from list_sites, optional for single-site accounts). The description only restates the document_id origin, adding little beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb+resource: it returns the text of one page/product/policy/file part identified by document_id. It also implicitly distinguishes itself from search_site_content by naming it as the id source. The phrasing is a bit awkward ('Actually Asked has read'), but the intent is unambiguous.

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

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

It establishes a clear workflow prerequisite: the document_id must come from search_site_content, so an agent knows to search before fetching. It does not state any when-not conditions or alternatives, but for a single-purpose fetch tool the context is sufficient.

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

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

Annotations already declare this is a safe, idempotent, closed-world read. The description goes beyond them with genuinely useful behavior: it distinguishes merchant-edited entries (which the system never rewrites) and flags that an entry may be out of date. It also explains conditional return content (suggestions indicate where publishing places them), which is real behavioral context rather than schema restatement.

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 that front-loads the primary payload (the answer as markdown) before running through secondary attributes. Every clause carries field-level information, though the trailing sentence about suggestions and suggested groups is compressed enough to read first as run-on.

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

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

For a 2-parameter read tool with a full output schema and complete annotation coverage, the description is sufficiently complete — the output schema carries the return structure, and the annotations cover the safety profile. Only the missing routing guidance against sibling list/search tools keeps this from being fully complete.

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

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

Schema description coverage is 100%: both site_id (site_…, from list_sites, optional for single-site accounts) and entry_id (faq_…) are fully documented in the schema. 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?

The description states a specific verb (retrieves) and resource (one FAQ entry) and enumerates the notable fields returned — answer as markdown, group, page rule, tag, pin, provenance — which distinguishes it from list_faq_entries. It never names a sibling explicitly, but the 'one entry in full' scope is clear enough to route correctly.

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

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

There is no when-to-use guidance and no mention of alternatives such as list_faq_entries or search_site_content. Usage is only implied by the name and the read-only annotations, leaving the agent to infer when a single-entry fetch is appropriate.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral value by describing the shape of what comes back (snippet, tag variants, per-platform placement) and pointing to check_install for verification, but it says nothing about auth requirements, failure modes, or behavior for unsupported platforms.

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 with no filler: the payload is front-loaded and the sibling routing note follows. The middle list is somewhat dense but every element maps to something the tool actually returns, so nothing needs cutting.

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

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

With an output schema present, the description needn't spell out return formatting, and parameter semantics are fully covered by the schema. What it provides — purpose, contents, and sibling routing — is sufficient for a read-only informational tool, though a note on unsupported platforms or required site context would round it out.

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

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

Schema description coverage is 100%, so both parameters are already documented in depth — the platform description even explains Shopify/Framer install paths and that Wix is unsupported. The description only alludes to the site key without adding format or default semantics beyond the schema, so the baseline 3 applies.

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

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

The description names the specific resource (install instructions for the FAQ widget) and enumerates exactly what the caller receives: the snippet with this site's key, the full FAQ page and tag variants, and where they go on the platform. It also explicitly contrasts with the sibling check_install, so an agent can distinguish the two without opening schemas.

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

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

It draws the line against check_install ("check_install confirms it's on a page"), implying this tool supplies instructions rather than verifying placement. That is clear contextual routing, but it stops short of an explicit "use this when / don't use it when" statement or any prerequisite (e.g. needing a site_id 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=false, and destructiveHint=false, so the safety profile is covered. The description adds which fields are returned (email optional, discardable flag), but says nothing about auth, permissions, or error behavior beyond what annotations provide.

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

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

A single front-loaded sentence enumerating the return fields. Efficient and well-structured, though the long comma-separated list is dense and could be trimmed against the output schema.

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

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

An output schema exists, so return values needn't be re-explained, yet the description enumerates them anyway. With 100% schema coverage and annotations covering safety, the definition is largely complete; only explicit when-to-use guidance is missing.

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

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

Schema description coverage is 100%, so both parameters (site_id, question_id) are already fully documented in the schema, including the site_id optionality caveat. The description adds no syntax or format 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?

States a specific verb (get) and resource (visitor question) and immediately enumerates the concrete payload: page asked on, highlighted text, answer given, matched FAQ, visitor email, discard status. This distinguishes it from list_questions (plural, collection) and update_question (mutation).

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 singular 'one visitor question' versus the sibling list_questions, but the description never explicitly says when to use this instead of list_questions or update_question. 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 cover the safety profile (readOnly, idempotent, non-destructive), so the description isn't obligated to restate it. It adds real behavioral context beyond the annotations: null means the value is inherited from the site, and a Shopify store has no widget look here because it is set in the theme editor — a non-obvious domain constraint.

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, no filler, and the content enumeration leads. The opening sentence is a somewhat dense run-on list, but every clause conveys real information about the returned fields 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 an output schema present, the description need not explain return formatting, and it covers the semantic edge cases (null inheritance, Shopify theme constraint) that structured data cannot. Only a slightly clearer statement of the retrieval action itself 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 single site_id parameter is fully documented in the schema (100% coverage), including the site_… format and the list_sites source. The description adds nothing about the parameter, so the schema carries the whole burden and the baseline of 3 applies.

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

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

The description enumerates exactly what this call surfaces — question count, heading, hint/ask item, and the visual preset/layout/colours/sizes — which clearly identifies it as the read of widget settings. It also names update_widget_settings as the mutating counterpart, so it is distinguishable from its nearest sibling 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 closing clause 'update_widget_settings changes them' establishes the read-vs-write boundary, and 'null is the site's own' tells the agent how to interpret absent values. There is no explicit 'use this when you need X' phrasing or stated exclusion, but the contrast with the update tool gives clear context.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety bar is covered. The description adds genuine behavior beyond that: the ordering rules for live entries (ungrouped first, then pins, then popularity) and the lifecycle rule that removed entries are never suggested or published again unless restored.

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 with no filler, and the resource definition is front-loaded ahead of the state semantics. The state descriptions are dense but each clause carries information the agent needs.

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

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

With an output schema present, the description need not explain return values, and the 8-parameter schema is fully documented. The description fills the two gaps the schema cannot: state meaning and ordering behavior. Remaining filter params (tag, query, group_id) are self-evident from their schema descriptions.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by expanding the terse 'live (default), suggested or removed' schema text into a real explanation of each state, which is the key parameter for this tool.

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

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

States a specific resource (a site's FAQ entries) and scope (short excerpt of each answer, full answer lives in get_faq_entry), which cleanly separates it from get_faq_entry and the other list_* siblings. An agent can identify the tool's job 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?

Explains the three state values and what each represents, and points to get_faq_entry when the full answer is needed, giving clear context for when to choose this tool. It stops short of explicit when-not conditions or naming other sibling list tools as alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real domain behavior beyond that: groups render on pages matched by their page rule or carrying the group tag, and the built-in General group is on the FAQ page rule and cannot be renamed or deleted. Auth requirements and rate limits are not mentioned.

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

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

Four sentences, front-loaded with the core identity and ordering, then visibility rules, the General special case, and return counts. Dense but each sentence carries domain meaning; the final counts sentence overlaps with the output schema slightly.

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

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

For a read-only single-parameter list tool with annotations covering safety and an output schema covering return shape, the description supplies the missing domain model (ordering, visibility rules, immutable General group). Little an agent needs to call it correctly is absent.

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 site_id parameter, so the schema already carries the semantics. The description only indicates site scoping generically ('A site's FAQ groups') without adding format or fallback detail. Baseline 3 applies 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?

The description states exactly what the tool surfaces: a site's FAQ groups in page-display order, characterized as the headings questions sit under. That clearly separates it from list_faq_entries, list_questions and list_page_rules. It stops short of a 5 because the verb is only implied and no sibling is named as a contrast.

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 statement and no named alternative. Usage is only implied: an agent wanting the group/heading structure rather than entries or questions would reach for this. Nothing states when not to use it or which sibling to prefer.

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 real behavioral context: results are newest first, the default filter, and the clarifying note that 'the merchant replies from their own email; nothing here sends mail' — which preempts any assumption of a write or mail side effect.

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, with the domain definition front-loaded ahead of ordering and filter semantics. The only minor cost is that the listing action itself is left implicit.

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 carry the safety profile. The description supplies the domain concept, ordering, default filter, and the no-email clarification — enough for an agent to call it correctly, with only usage routing to siblings left unaddressed.

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

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

Schema coverage is 100%, so page/per_page/site_id are fully documented in the schema and the baseline is 3. The description only slightly enriches the filter enum by spelling out what 'waiting' means ('waiting for the merchant's reply') and the default; it adds little for the other three 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?

The description defines the resource precisely ('visitors who left their email under a question the site couldn't answer') and states ordering (newest first), which is more than the name/title offer. It never uses a list/return verb explicitly, but the domain concept plus ordering makes the operation unambiguous and separable from siblings like list_questions and update_lead.

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

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

It conveys the default filter ('waiting for the merchant's reply (the default)') and the alternative values, which implies usage, but gives no explicit when-to-use vs alternatives (e.g. update_lead, get_question) or prerequisites. Guidance is inferable rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and non-open-world, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the built-in Everywhere (/*), Home (/) and FAQ page (/faq) rules cannot be renamed or deleted, and only the FAQ page's paths are mutable — information that shapes how results should be interpreted.

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 paragraph that front-loads the domain definition and wastes no words. It is on the longer side for a list tool and leads with concept rather than purpose, but every sentence carries relevant information about rule matching and built-in rules.

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, and annotations cover the safety profile. The description supplies the domain model needed to interpret the listed rules, including the immutable built-ins. Only the absence of when-to-use routing keeps it from being fully complete.

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

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

Schema description coverage is 100%, so site_id (including the 'optional when the account has one site' note and the list_sites provenance) is fully documented in the schema. The description adds no parameter-level 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?

The title supplies the verb (List) and the description thoroughly defines the resource (page rules, their path-matching semantics, and the built-in Everywhere/Home/FAQ rules). An agent can infer this returns a site's page rules and distinguish it from create_page_rule/update_page_rule/delete_page_rule. However, the description body itself never states the action, only defines the concept, so it falls short of a self-contained verb+resource statement.

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, no mention of the sibling tools it complements (create_page_rule, update_page_rule), and no exclusions. The reader must infer from the name that this is the read/list counterpart to the mutation tools.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, yet the description adds genuine domain behavior: suggestions change nothing until accepted and a declined suggestion is permanently suppressed. That result-consequence detail is exactly the kind of context annotations cannot express. It stops short of mentioning pagination or response shape, but the output schema covers that.

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 core concept (what a suggestion is) leads. The opening is slightly indirect in that it describes the suggestions rather than the list action, but every sentence earns its place.

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

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

With an output schema handling return values and read-only annotations covering the safety profile, the description only needs to explain what a suggestion is and its lifecycle, which it does. It is complete enough to call correctly, with the only gap being the absence of explicit sibling routing.

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

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

Schema description coverage is 100%, so all four parameters (page, site_id, per_page, target_id) are already documented in the schema. The description's 'only those for one group or page rule' merely restates the target_id filter without adding format or behavior 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?

The description clearly conveys that this returns placement suggestions for live FAQ entries (a target group or page rule), which is a specific resource. However, it never uses the verb 'list' and does not name or distinguish itself from the sibling resolve_placement_suggestions, so sibling differentiation is left implicit.

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

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

The lifecycle note ('Nothing moves until the merchant accepts; a declined suggestion is never made again') implies this is the read step for reviewing pending suggestions, and 'Optionally only those for one group or page rule' hints at the filter use case. But there is no explicit when-to-use statement and no routing to alternatives such as resolve_placement_suggestions.

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 safety profile is covered. The description adds useful behavior beyond that: results are newest-first, archived questions are hidden unless archived=true, and each status carries a distinct operational meaning. No auth or rate-limit context, but the added value is well above annotation baseline.

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

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

The purpose and sort order lead, followed by the status taxonomy and two short routing notes. It is information-dense but every clause (status meanings, archived default, get_question pointer) 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 no explanation, and pagination is covered by the schema's next_page note. Combined with sort order, default filtering, and status semantics, nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely enriches the status enum by defining answered, matched, unanswered, and out_of_scope — meanings the schema lists only as bare values. It also confirms the archived default, reinforcing the schema.

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

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

States a specific verb (list) and resource (visitor questions asked on a site) and describes the scope accurately with sorting order. It explicitly differentiates from the sibling get_question, which holds the full detail, so an agent can route correctly.

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

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

It gives clear context: this is the enumeration view, and get_question should be used for full detail. It also explains the default exclusion of archived questions. It stops short of stating explicit when-not conditions, but the alternative and the default filter are both spelled out.

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

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

Annotations already establish readOnly, idempotent, non-destructive, so the safety profile is covered. The description goes beyond them by disclosing domain behavior an agent could not infer: plan-gated capabilities (groups from Starter, page rules and tags from Growth) and the aggregation of waiting items such as questions this month and leads awaiting reply.

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 front-loaded sentence naming the resource, followed by a tightly packed enumeration of return contents. No filler, and the closing 'Start here' is placed where it functions as a call to action 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 an output schema present and no parameters, the description need not document return shapes, yet it usefully previews the notable categories (plan entitlements, pending work). For a zero-arg entry-point tool it is essentially complete; only explicit sibling routing 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 parameter-related for the description to clarify or compensate for.

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 the resource (sites in the connected account) and enumerates precisely what each entry contains — plan/tier entitlements, paused state, widget liveness, and pending items — so an agent knows what it gets back without opening the output schema. It stops short of contrasting itself against sibling readers like check_install or get_widget_settings, though 'Start here' hints at its entry-point role.

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?

'Start here' is a real directional cue that this is the first call to make, which is meaningful given the large sibling set. But there is no explicit when-not, no statement of prerequisites, and no routing to the specific siblings (list_questions, list_leads, list_placement_suggestions) whose data it summarizes.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond that: it explains widget-parity semantics and the deterministic ordering of sections (entries in no group first, then each group in order).

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

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

Three sentences, front-loaded with the core purpose and followed by enum semantics and usage. Slightly dense in the first sentence ('worked out exactly as the widget does') but no sentence 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, the description needn't explain return values, and it adequately covers purpose, layout semantics, and usage. Nothing essential is missing for an agent to call it correctly, though optional-parameter behavior (tag/site_id) is left entirely to the schema.

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

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

Schema coverage is 100% and the enum is already documented in the schema, giving a baseline of 3. The description adds real meaning by explaining what each layout value resolves to behaviorally (widget = top entries a normal snippet shows; full = a full FAQ page).

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 clear verb (preview) and resource (the FAQ on one page), and specifies that it computes the result 'exactly as the widget does', including what the output contains (sections, then questions). It is specific and distinguishable from settings/content tools, though it never names a sibling to contrast against.

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

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

'Use it to check a page rule or tag change' gives an explicit, task-driven context for invocation. It doesn't state when NOT to use it or name an alternative tool, so it falls short of full routing guidance.

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

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

Annotations declare non-read-only, non-destructive, non-idempotent, open-world, so safety is partly covered. The description adds materially beyond that by disclosing side effects: entries publish 'as they are', a group is created for the proposed group, and a page rule is generated when the site lacks one. This is exactly the kind of hidden-mutation context an agent needs.

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

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

Three densely packed sentences, front-loaded with the action and its side effects, then the parameters, then the prerequisite workflow. The parenthetical '(made, with a page rule for its page, when the site doesn't have it yet)' is grammatically awkward but carries real 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 not be explained. The description covers the mutation's side effects, parameter selection, and the recommended read-verify-edit workflow, leaving little an agent would need to guess before invoking.

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

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

Schema description coverage is 100%, so all three parameters (all, site_id, entry_ids) are already documented in the schema; baseline is 3. The description only restates the entry_ids-vs-all:true choice and adds no format or constraint detail beyond the schema.

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

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

States a specific verb (publishes) and resource (suggested FAQ entries) and adds distinguishing scope: entries are published as-is under their proposed groups, with page rules created when missing. An agent can immediately tell this apart from create_faq_entry or update_faq_entry.

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

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

Gives explicit selection logic ('Give entry_ids, or all: true for every waiting suggestion') and a recommended workflow naming sibling tools (get_faq_entry to read, update_faq_entry to fix). It does not state when *not* to publish, so it falls just short of a 5, but the activation conditions are clear.

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

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

Annotations already declare destructiveHint=false and idempotentHint=true, but the description explains WHY: the entry is retained, so the question is never re-suggested or republished, and can be recovered via restore_faq_entry. That retention/reversibility detail is genuine added value the annotations cannot convey. It stops short of stating auth/permission requirements or scoping behavior across sites.

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

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

One tight sentence covering action, dual scope, retention consequence, and recovery path, with the core action front-loaded. 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 need not be described, and the annotations plus description together cover safety, idempotency, and reversibility for this mutation. The only remaining gap is that which sibling to use for suggestion dismissal versus question-level operations is 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?

With 100% schema description coverage, both entry_id and site_id are already fully documented in the schema, including the site_…/faq_… id formats and the single-site optionality. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource and immediately clarifies the two scopes it covers: removing a live FAQ entry and dismissing a suggestion. It also distinguishes itself from the superficially similar sibling delete_faq_group by making clear this is a removal of a single entry, not a structural delete.

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 both uses (live entry vs suggestion) and names the inverse operation, restore_faq_entry, which is exactly the alternative an agent would otherwise have to guess at. It does not, however, exclude the nearby dismiss-style siblings such as discard_question, leaving a small ambiguity about which tool to pick for question-level dismissal.

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 non-destructive, idempotent, open-world behavior, so the safety profile is covered. The description adds the non-obvious trait that this is a whole-collection replacement ('Give every group') and that ungrouped questions define the base order, which the agent would not know from the hints alone.

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

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

Two short sentences, front-loaded with the core action; nothing is wasted. The clause 'after the questions in no group' is somewhat awkward to parse, which slightly weakens structure.

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

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

With an output schema present and annotations covering safety, the description only needs to convey intent and input semantics, which it does, including the full-set requirement. It is largely complete for a straightforward reordering tool.

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

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

Schema description coverage is 100%, so both parameters are already documented, and the description essentially repeats the schema's 'Every group (grp_…), in the new order'. It adds ordering context but no new syntax or format detail, matching the baseline of 3.

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

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

The description states a specific verb and resource ('Puts a site's groups in a new order') and even clarifies the resulting display order, which distinguishes it from siblings like reorder_pinned_entries or update_faq_group. It does not explicitly name a sibling, but the purpose is unambiguous.

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

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

'Give every group' is a genuine operational directive about how to call it (full set, not a subset), but there is no when-to-use/when-not guidance or named alternative for changing order in other ways. Usage is implied rather than explained.

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 non-read-only, idempotent, non-destructive, open-world, so the safety profile is covered. The description adds real behavior beyond that: it discloses the resulting ordering rule (pins precede frequency-ranked entries) and the constraint that every pinned entry must be supplied, implying a full-replacement semantics rather than a partial edit.

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 operation and its effect, then the completeness requirement, then the alternative tool. Every sentence carries information an agent needs; 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 no explanation, and the description covers the operation, its ordering semantics, the required input completeness, and the sibling responsible for pin/unpin. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds meaning beyond the schema: 'Give every pinned entry of the group' clarifies that entry_ids must be exhaustive rather than a partial reorder, which the schema's 'in their new order' phrasing does not make explicit.

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 (reorder) and resource (a group's pinned entries) and explains the resulting semantics: pins show first in this order, ahead of entries ranked by visitor frequency. This distinguishes it cleanly from the sibling reorder_faq_groups and from update_faq_entry, which handles pinning itself.

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

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

Explicitly routes the related pin/unpin action to update_faq_entry, which is a genuine alternative-task pointer. However, it gives no when-not guidance (e.g., what to do for unpinned ordering, which is presumably automatic by ranking) and doesn't contrast with reorder_faq_groups.

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

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

Annotations declare destructiveHint=true and idempotentHint=false, but the description goes further by disclosing consequences the annotations cannot convey: accepting moves the entry under the group or applies the page rule, settling other suggestions of that kind, and a declined suggestion 'is never made again'. That irreversibility/persistence detail is genuinely useful. It still omits permission or rate-limit context, 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 sentences, front-loaded with the action and consequence, then the two input modes. Dense but each clause carries information; minor verbosity in 'settles its other suggestions of that kind'.

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 both decision paths and the bulk-target behavior. It leaves the interaction between suggestion_ids and target_id (mutually exclusive or combined) implicit, 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 coverage is 75%, so most parameters are already documented, including target_id's group/page-rule semantics. The description restates the suggestion_ids vs target_id tradeoff but adds no format, limit, or precedence detail beyond the schema. Baseline 3 is appropriate.

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

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

States specific verbs (accepts/declines) on a specific resource (suggested placements) and explicitly ties the resource back to its producer, list_placement_suggestions. An agent can distinguish this mutation tool from the listing sibling without opening either schema.

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

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

The description establishes the workflow context (suggestions come from list_placement_suggestions) and gives clear guidance on the two invocation modes: individual suggestion_ids or a bulk target_id for a group/page rule. It does not state when NOT to use the bulk mode or any exclusions, 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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so safety is covered. The description adds genuine behavioral context beyond that: the restoration destination is state-dependent (back into the FAQ if it was live, back to suggestions if it was a dismissed suggestion), which is not derivable from annotations or schema.

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

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

A single front-loaded sentence with a colon that splits the two restoration paths cleanly. No filler, no repetition of the title or schema content.

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?

Annotations carry the safety profile and an output schema exists, so return values need not be explained. The description covers the key non-obvious behavior (state-dependent destination), though it says nothing about what happens on an invalid or already-live entry_id.

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

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

Schema description coverage is 100% and both parameters (site_id, entry_id) are fully documented in the schema with id formats and fallback guidance. The description adds no parameter-level detail, which is acceptable given the schema does the heavy lifting — baseline 3.

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

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

The description gives a specific verb+resource ('Brings a removed entry back') and explains the two conditional outcomes, so an agent can distinguish it from remove_faq_entry or discard_question. It stops short of naming the counterpart tool explicitly, keeping 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?

Usage is implied: call this when an entry was previously removed or a suggestion dismissed. There is no explicit when-to-use framing, no statement of prerequisites, and no named alternative for undoing a removal versus re-drafting suggestions.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: it returns ranked passages with their page, and it imposes a citation rule ('cited as a file: never link to them') that is not derivable from annotations.

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

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

Three tightly written sentences: scope of corpus, return shape, then usage/citation rules. The most decision-relevant information (what corpus is searched) is front-loaded, and no sentence is filler.

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

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

With an output schema present and 100% parameter coverage, the description only needs to add corpus scope, intended use, and the file-citation convention — and it does all three. Nothing an agent needs to call or interpret this tool is missing.

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

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

Schema description coverage is 100%, so query, site_id, and source_type are all fully documented in the schema, including the 'site's own words' phrasing and the enum values. The description adds no additional parameter-level semantics, so the 3 baseline 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 (full-text search) and precisely scopes the resource: 'everything Actually Asked has read for a site (its pages, products, policies and uploaded files)'. This clearly separates it from the many CRUD siblings for FAQs, page rules, and sites.

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

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

Gives explicit usage direction: 'Write and check FAQ answers from these, not from general knowledge,' which covers both a when-to-use and an implicit when-not-to-use (general model knowledge). It does not, however, name a sibling alternative for narrower lookups (e.g., get_document).

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

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

Goes well past the annotations by disclosing non-obvious side effects: editing wording reattributes the entry to the merchant, clears 'may be outdated', and publishes a suggestion under its proposed group; moving or pinning alone changes nothing else. This is exactly the kind of behavioural context an agent cannot infer from hints alone.

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

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

Dense but front-loaded: the mutating verb and editable field list come first, then the side-effect caveats, then the alternative tool. Slightly clause-heavy in the middle, but no sentence is filler.

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

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

For an 8-parameter mutation with full schema coverage, an output schema, and rich annotations, the description supplies the remaining gaps: patch semantics, reattribution side effects, and the publish-a-suggestion path. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds semantic interplay the schema cannot: which fields count as 'moves' versus content edits, that group_id governs where the freshly published suggestion lands, and that omitted fields are preserved. It does not restate per-parameter formats, which is fine.

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?

Opens with a specific verb ('Changes') and resource ('a FAQ entry') and enumerates exactly which fields are editable: question, answer, group, own page rule, own tag, pin. It is clearly distinguishable from siblings like update_faq_group, update_page_rule and update_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?

States the key alternative explicitly: 'To publish a suggestion as it is, use publish_faq_entries,' with the condition that selects it. It also implies the partial-update contract ('what you leave out stays'), but it does not contrast against create_faq_entry or explain when editing is preferable to deleting/re-creating.

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 openWorldHint=true, so the safety profile is covered. The description adds behavior the annotations don't carry: the immutable 'General' group and a plan gate ('Growth and up') on placement features, both of which affect whether a call will succeed.

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 clauses, front-loaded with the core action, then the constraint, then the verification step. No filler, no repetition of the title or schema.

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

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

With an output schema present, return values needn't be described, and annotations cover the safety profile. The description adds the key domain constraints and a verification tool, leaving only minor gaps around partial-update semantics and whether omitted fields are cleared or preserved.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes marginally beyond the schema by mapping the updatable fields to intent ('renames' for name, 'changes where it shows' for page_rule/tag) and attaching a plan-tier constraint to the tag parameter that the schema does not mention.

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 ('Renames a group') and enumerates exactly what can be changed: name, page rule, tag. This clearly separates it from create_faq_group, delete_faq_group, list_faq_groups, and from update_faq_entry/update_page_rule, which operate on different resources.

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

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

Gives an explicit when-not ('General can't be renamed') and routes the agent to a verification path ('Check the result on a page with preview_faq_for_page'), which is real usage guidance. It stops short of stating prerequisites such as required permissions or what happens on partial updates.

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, destructiveHint=false and readOnlyHint=false, so the safety profile is covered. The description adds the non-obvious clarification 'Nothing here sends mail', which matters because the tool name could imply notifying the visitor, and it clarifies the reversible two-state 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 short sentences, the state change is front-loaded, and the important 'no mail is sent' caveat is placed last without padding. 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 and annotations covering idempotency and safety, the description need not explain return values. It supplies the semantic nuance and the no-email caveat, leaving only minor gaps around when to prefer this over other lead/question tools.

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

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

Schema coverage is 100% and both the replied boolean and lead_id/site_id are documented in the schema. The description's 'or back to waiting' largely restates the schema's 'false, waiting again', so it adds little beyond what the structured fields already provide.

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

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

States a specific verb and resource ('Marks a lead replied') and defines the two-state semantics of the operation. It is easy to tell apart from sibling tools like update_question or list_leads by resource, though it never explicitly contrasts itself with them.

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 'once the merchant has answered the visitor from their own email, or back to waiting' implies when each state applies, which is real usage context. However it gives no guidance on when to call this tool versus alternatives and no explicit exclusions.

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

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

Annotations already declare the full safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=true, openWorldHint=true), so the description only needs to add context. It contributes the useful editing restrictions on reserved pages, but says nothing about partial-update behavior (e.g., whether omitting name leaves it unchanged) or idempotency beyond what the annotation states.

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 with the core action front-loaded and no filler. The second sentence is slightly awkward ('Everywhere, Home and FAQ page') but remains short and information-dense.

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, rich annotations, and 100% schema coverage, the description only needs to state the operations and the reserved-page constraints — both of which it does. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the operative semantics of the two editable fields (rename vs full path replacement), but the schema already states 'replacing the ones it has', so little meaning is added.

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 both concrete operations ('renames' and 'replaces its paths') on the specific resource, so an agent immediately knows this is the update counterpart to create_page_rule/delete_page_rule. It stops short of naming siblings explicitly, which is the only thing keeping it 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?

'Everywhere, Home and FAQ page can't be renamed, and only the FAQ page's paths can change' gives real preconditions for when the call will succeed or fail. However, there is no guidance on when to reach for this tool versus create_page_rule or delete_page_rule, so usage is implied rather than stated.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond them: archiving moves the question to an Archived tab yet it "still counts in the numbers," which tells the agent this is a reversible, non-deleting operation. It does not mention permission or auth requirements.

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

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

A single sentence with the core action front-loaded ("Archives a visitor question"), followed by the parenthetical consequences and the reverse case. The parenthetical is dense but each clause carries useful information; nothing is redundant.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The one remaining gap is disambiguation from the sibling discard_question, which shares the question-mutation space.

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 all three parameters are documented in the schema, so the baseline is 3. The description's "or brings it back" reinforces the boolean semantics of the required `archived` parameter but adds nothing the schema does not already state.

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 — archiving (and un-archiving) a visitor question — and clarifies the generic name 'update_question' by explaining the real operation is a boolean archive toggle. It does not distinguish this from the nearby sibling discard_question, which an agent would plausibly confuse it with.

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

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

"a visitor question the merchant has dealt with" gives an implied usage condition (only for handled questions). However, no alternatives are named and no when-not guidance is given, so the agent gets no explicit routing between update_question, discard_question, and get_question.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered; the description still adds meaning to that profile by explaining why writes are potentially destructive ('null puts a field back to its default') and that changes 'Live within a minute'. It also discloses a non-obvious constraint ('Fonts always come from the site') and a preset interaction rule that the annotations cannot express. It does not cover auth/permission requirements, but the added behavioural detail is substantial.

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

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

The purpose is front-loaded and each following sentence carries distinct information: partial-update semantics, the fonts constraint, propagation timing and the preview url. The first sentence is overstuffed, burying the 'except on Shopify' carve-out mid-clause and forcing the reader to parse two separate scopes in one breath, but overall there is very little filler for the amount of behaviour conveyed.

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 11 optional parameters, a nested styles object, rich annotations and an output schema, the description covers the essentials: partial updates, reset semantics, platform restrictions, propagation delay and where the merchant validates the result. It omits how site_id is obtained (the schema points to list_sites) and any warning about the faq_size-vs-pins constraint, both of which are low-severity gaps given schema coverage.

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%, including a fully documented nested styles object with per-field descriptions, so the schema already carries parameter meaning and a 3 is the correct baseline. The description adds little parameter-level detail beyond echoing the field list and restating the null-resets-to-default rule that the schema also states. No compensating value is needed here, but none is added either.

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 concrete verb and resource ('Changes what the FAQ widget says and how it looks on a site') and then enumerates the settable surface: question count, heading, hint, ask item, preset, layout, colours and sizes. An agent can immediately tell it apart from update_faq_entry or update_faq_group, which touch FAQ content rather than widget presentation. It stops short of naming the read counterpart (get_widget_settings), so it is clear but not explicitly differentiated from siblings.

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

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

It tells the agent how to call it ('Give only what changes; null puts a field back to its default') and flags the platform restriction 'except on Shopify', which is genuine usage context. However, it never says when to reach for this tool rather than a sibling such as update_faq_entry or update_page_rule, and no prerequisites or exclusions beyond Shopify are stated. Usage is implied rather than specified.

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