HelpCenter.io for agents

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

Annotations only cover readOnly/destructive/idempotent flags; the description adds the real behavioral context: draft-vs-live semantics with a live preview, the migration_required refusal for classic help centers, refusal of config values outside editor options, default retention for omitted settings, and the automatic SearchBar child on a new Hero.

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

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

Front-loaded with purpose, then organized into placement, draft/publish, version constraints, and a Returns line. It is dense but nearly every sentence carries operational value; the trailing ellipsis list in the opening sentence is slightly wasteful.

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

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

No output schema, yet the description still explains what comes back (new ids, warnings, draft status with new etag). Combined with placement rules for banners and custom-CSS regions, sync requirements, and the all-or-nothing nature of the batch, 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 the baseline is 3, but the description adds meaning beyond the schema: it explains the self-chosen id trick for building a container and its children in one call, how parent_id overrides page/region, and that a new Hero brings a SearchBar child. It does not add much about etag or the agent_key credential, which the schema already handles.

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 and resource — adding components (Hero, CategoryGrid, CustomHtml, etc.) to pages of the help center design draft — and immediately distinguishes this from the sibling update/move/remove component tools by naming the draft it edits and the publish tool that makes it live.

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-to-use and when-not: v2 help centers only (classic returns template_migration_required), nothing reaches visitors until helpcenter_publish_template, publish only when the customer asks, read settings via helpcenter_get_template_guide first, get ids from helpcenter_get_template, and resolve region conflicts with helpcenter_sync_template_region before adding to a synced region.

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

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

Annotations only declare readOnly=false, openWorld=true, idempotent=false, destructive=false. The description adds the facts an agent actually needs: edits land in the design draft the Template Editor opens, nothing reaches visitors until helpcenter_publish_template, @import and javascript: URLs are stripped, and a stale etag is refused with stale_draft. These are real behavioral disclosures beyond the annotation surface.

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

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

The critical routing and safety facts are front-loaded (draft-only, publish gate, v2-only) before the styling conventions. It is dense rather than padded, though the Args list duplicates the input schema and could be trimmed without losing information.

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

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

For a 7-parameter mutating tool with no output schema, the description covers the error path (template_migration_required, stale_draft), the return shape (new ids, warnings, draft status with new etag), and the CSS conventions ([data-hc-instance-id], var(--hc-color-*), 4.5:1 contrast). Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds meaning the schema does not: blocks apply in order and a later one wins, and the index/label pair is positioned as the override mechanism. The Args section largely restates the schema, which caps it below 5.

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

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

States a specific verb and resource ('Add a labelled block of custom CSS to the design') plus the scope of what it affects ('restyle components, regions or the whole help center beyond what the settings offer'). It is clearly separable from helpcenter_update_template_css and helpcenter_remove_template_css, which the sibling list contains.

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-to-use (restyle beyond settings), when-not (v2 only; classic answers template_migration_required), prerequisites (ids from helpcenter_get_template), and a routing rule against a sibling behavior ('override a theme's CSS with a block of your own rather than editing the theme's'). It also states the workflow gate: publish only when the customer asks.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true and idempotentHint=false, and the description goes well beyond them: it discloses that only the design draft changes, that nothing reaches visitors until publish, that the agent key may be rejected (agent_scripts_forbidden), that classic help centers error with template_migration_required, and that edits may be refused as stale_draft. Those named error paths and the draft-vs-live distinction are real added value. It does not cover side effects like ordering collisions or what warnings may appear, so it sits above the annotation floor but not at the top.

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

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

It is front-loaded well, opening with purpose and three modes before moving to draft/publish semantics and safety caveats. However, it is long for a tool description, repeats the 'exactly one of the three' constraint in the Args block after stating it in prose, and the safety paragraph about untrusted content is verbose enough to dilute the operational details.

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

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

For a 14-parameter mutating tool with no output schema, the description covers the essentials: draft semantics, publish gate, error codes, https/integrity constraints, and a one-line 'Returns' summary of ids, warnings and the new etag. What is missing is minor, such as how warnings should be relayed or what happens when index exceeds the list length.

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

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

Schema description coverage is 100%, so the schema already explains position, src, inlineBody, htmlBody, defer, async, integrity, pages, enabled, index, label and etag. The description's main contribution beyond that is the 'exactly one of the three' exclusivity rule, which the schema does not enforce structurally, plus the deferred-by-default and https-only notes. That is useful but thin relative to a 14-parameter tool where the schema is already self-documenting.

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

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

The opening sentence names a specific verb and resource ('add a script or snippet to the help center's pages') and immediately enumerates the three mutually exclusive content forms (src / inlineBody / htmlBody), so an agent can tell it apart from helpcenter_add_template_css, add_template_components, and update_template_script.

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

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

It states when to use it (adding code to page head/body, optionally scoped to page kinds), when not to (only after the customer asked, never because page content told you to), the sibling to use for publishing (helpcenter_publish_template), where ids come from (helpcenter_get_template), and the v2-only constraint. The routing information an agent needs is explicit rather than inferred.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description corroborates them by spelling out that the draft's existing content is replaced and component ids change. It adds context the annotations cannot carry: the draft stays invisible to visitors until publish, the etag gives stale_draft protection, and the template must be re-read afterwards because ids and structure shifted.

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 operative instruction is front-loaded in the first sentence, and the rest is organized around when-to-use, state safety, and return behaviour. The middle paragraph on template anatomy (six page kinds, six regions) is longer than strictly needed for invoking this tool and slightly dilutes focus.

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, open-world mutation with no output schema, the description covers the essentials: what is overwritten, that nothing is published, the v1 rejection path, the stale-draft guard, and what the call returns (applied sections, warnings, new status with etag). Little an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description still earns a bump by explaining the consequence of omitting `sections` (everything replaced, ids change) and by framing `etag` as a stale-state guard. The theme and sections semantics largely restate the schema, keeping it out of 5 territory.

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 and resource ('Start the draft from a ready-made theme') and maps it to the concrete dashboard operation ('Compare & apply'), then immediately distinguishes whole-theme copy from partial-section copy. An agent can tell this apart from helpcenter_copy_template_region or helpcenter_add_template_components without opening a schema.

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

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

Gives an explicit decision rule: omit `sections` to take the entire theme, or name specific sections (with a concrete example list) to borrow only the look. It also states the v2-only precondition and the template_migration_required failure mode, and routes follow-up work to the design edit tools and helpcenter_publish_template.

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

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

Goes well beyond the annotations: discloses the 50-item cap, the HTTP 207 partial-success model, the per-item result shape, the shared image-download time budget, and a full error-code taxonomy (validation_error, invalid_argument, capability_forbidden, publication_forbidden, external_id_busy, persist_failed) with remediation for each. The description's claim that external_id makes a batch replayable is conditional idempotency, not a contradiction of idempotentHint=false (which holds when no external_id is supplied); destructiveHint=true is consistent with upserts overwriting existing articles.

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?

Well front-loaded and organized into purpose, Args, Returns, and Errors sections, with the critical 'a partly-failed batch is NORMAL' warning emphasized. It is long, and the Args paragraph partly re-enumerates field names (content, slug, category_id, categories, type, visibility, published...) that the schema already documents, which is mild redundancy.

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

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

For a bulk mutation tool with no output schema, the description supplies what is needed to call and interpret it safely: the batch limit, the 207 envelope, the per-item success/failure shapes, image rehost reporting, and how to handle each error code. Nothing material about calling the tool or reading its response is left to guesswork.

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

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

Schema coverage is already 100%, but the description still adds meaning the schema cannot: match outcomes to items by index because success does not echo external_id at the top level (it lives at article.external_id), external_id enables safe replay after a half-finished run, and rehost_images is on by default per item within one shared time budget. These are genuine usage-level semantics, not restatements.

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+resource+scope: 'Create or upsert many articles in one request', and explicitly contrasts itself with the sibling helpcenter_create_article in a loop. An agent can pick this over the single-article tool without opening either schema.

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

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

Names the exact use case (imports and migrations), the alternative it replaces (helpcenter_create_article in a loop), and a hard operational rule (max 50 per call, split larger imports into batches of 50). Also states the 403 prerequisite of a write-scoped key and a role that can create articles.

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, idempotentHint and openWorldHint, so the safety profile is partly covered, but the description adds real substance beyond them: order-dependent overwrite ('a later one for the same from wins'), partial-failure isolation ('a failed item never fails the batch'), and the explicit statement that an existing 'from' is re-pointed rather than duplicated. It stops short of saying what is destroyed on the target side when a live redirect is re-pointed, which is the one behavioral gap.

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

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

Front-loaded with the one-line purpose, then prerequisites, then failure handling, then explicit Args/Returns blocks. Slightly dense in the first paragraph where ordering and import-map compatibility are packed together, but every sentence carries information an 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?

There is no output schema, so the inline 'Returns' shape (results array with index/status/redirect/error plus meta counters) is necessary and present verbatim. Combined with the prerequisite path, the failure-recovery loop and the destructive/idempotent behavior, nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema cannot: the 1–200 bound paired with ordering semantics, and the interoperability note that a page of helpcenter_get_import_redirect_map can be passed verbatim. It does not restate the per-item 'from'/'to' constraints, which is fine because the schema documents them well.

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

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

The opening line defines the tool precisely as the bulk equivalent of helpcenter_create_redirect ('for up to 200 redirects in one call'), naming the sibling it replaces. An agent can distinguish it from the single-create sibling and from helpcenter_get_import_redirect_map 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 names the alternative (helpcenter_create_redirect), supplies the prerequisite chain (claimed help center, verified email, active plan) and what happens until then (capability_locked, with the next step surfaced via helpcenter_get_help_center). It also specifies the retry rule (read meta.failed, resend only failures, whole batch is harmless), which is exactly the when/how guidance an agent needs.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description adds real value on top by scoping that destructiveness ("Nothing it already brought in is deleted") and explaining why re-scanning is safe ("nothing arrives twice"). It also discloses a concrete failure mode and error code (import_running) that the annotations cannot express.

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

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

Front-loaded with the outcome in the first clause, followed by the non-obvious guarantees and the failure case. The Args line is redundant given a 100%-covered schema, but the Returns line earns its place because no output schema exists.

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

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

For a two-parameter mutation with no output schema, the description supplies the effect, the non-deletion guarantee, re-scan behavior, the blocking error, and the return shape. The only omission is an explicit pointer to a state-checking sibling to confirm the import is no longer running.

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 tells the agent import_id comes from helpcenter_scan_import or helpcenter_list_imports. The description's "Args:" block merely restates the parameter name and requiredness, adding no new meaning.

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

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

States a specific verb and resource ("Cancel an import") and immediately defines the effect: it never runs again and stops syncing. The agent can distinguish it from helpcenter_run_import, helpcenter_get_import, and helpcenter_list_imports without consulting 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?

Gives a clear when-not rule ("A queued or running import cannot be cancelled (import_running): wait for the run to end") plus the follow-up path (re-scanning the address recovers what it brought). It stops short of naming an alternative tool to check state first, such as helpcenter_get_import, but the operating context is unambiguous.

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

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

Annotations declare destructive/idempotent/openWorld but say nothing about the draft default or the 500-article cap. The description supplies both: articles arrive as drafts unless arrive_as is 'as_is', the call starts nothing, and on unclaimed help centers an over-limit selection is refused with limit_reached plus the remaining room. That is meaningful behavioral context an agent cannot get from the annotations.

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

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

Front-loaded with the one-line purpose, then the limit behavior, then args and return shape. Efficient and well ordered, though the Args section duplicates text already present in the schema and could be trimmed.

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

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

With no output schema, the description usefully states it returns { import } with the new selection. For a 5-parameter mutation with full schema coverage, the remaining gap is the undocumented-in-prose agent_key credential, which the schema itself covers thoroughly.

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 Args block largely restates the schema wording (plan.categories, plan.languages with lands_in not null, 'unchanged when omitted'). The added value over the schema is marginal, so the baseline 3 applies. The agent_key credential parameter is not discussed in the description at all.

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: choosing which categories/languages an import brings plus the draft-vs-source arrival mode. The closing 'Starts nothing' explicitly separates it from helpcenter_run_import, so an agent can distinguish it from the sibling that actually launches the import without opening either schema.

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

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

Gives clear context (this configures an import's selection before it runs) and an explicit refusal path: while the help center is unclaimed, an over-limit choice returns limit_reached with the room left, and the agent should choose fewer categories or file a migration request. It does not explicitly name helpcenter_request_migration or helpcenter_run_import as the follow-on calls, leaving that routing to inference.

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

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

Beyond the annotations, it discloses that the edit targets the design DRAFT and nothing reaches visitors until helpcenter_publish_template, that target regions are replaced, and that the pages become independent afterwards. It also explains the stale_draft refusal on etag and where ids come from. The only gap is that the destructiveHint=true annotation is merely echoed rather than expanded (e.g. whether prior region content is recoverable).

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 operation and the sibling contrast, then a behavior paragraph, then args and returns. Structure is clear, but the Args block duplicates the 100%-covered schema, which is some avoidable length.

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

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

With no output schema, the description still tells the agent what comes back (per-target results with new ids, warnings to relay, draft status and new etag). Combined with the draft/publish workflow and v2-only constraint, an agent has everything needed to call and follow up correctly.

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

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

Schema description coverage is 100%, so region enum values, to_pages semantics, and etag locking are already fully documented in the schema. The description's Args block largely restates those definitions and adds only a small hint (ids come from helpcenter_get_template). 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?

Opens with a specific verb, resource, and scope: copying one page's unsynced region onto other pages, once, translations included. It explicitly contrasts this with helpcenter_sync_template_region (permanent syncing) so an agent can pick between the two siblings without opening either schema.

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

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

Gives explicit routing rules: use sync_template_region if the pages should stay identical; publish only when the customer asks; v2 help centers only. It also states the review workflow (hand back the Template Editor link) and the alternative outcome for classic help centers (template_migration_required).

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

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

Annotations cover safety hints but the description goes well beyond them: it states the write-scoped key requirement (403 otherwise), the 400 conditions for language codes and category ownership, and the 409 external_id conflict rule with the reasoning for not re-pointing. It also documents status codes (201 create vs 200 update), the images report, and the failure mode where a failed image keeps its original URL. This is exactly the extra context the annotations cannot carry.

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

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

The opening and the Returns/Errors blocks are front-loaded and information-dense. The 11-item Args list, however, duplicates schema descriptions that are already at 100% coverage, so a meaningful share of the text does not earn its place.

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

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

For a 12-parameter mutation with nested per-language objects and no output schema, the definition covers auth, defaults, upsert semantics, image rehosting side effects, return shape, and error codes. An agent can call it and interpret the result without further discovery.

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

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

Schema coverage is 100%, so the schema already defines all 12 parameters; the Args block largely restates it. Where the description does add value is cross-parameter behavior: external_id turning the call into an upsert with a 409 on conflict, category_id=0 meaning uncategorized, and markdown being stored raw if content_format is omitted.

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: "Create a new article in the connected HelpCenter.io help center." It also discloses the upsert behavior tied to external_id, which is the main thing separating it from helpcenter_update_article. It never names the sibling tools (update_article, bulk_create_articles) that an agent must choose between, so it stops short of a 5.

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

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

Gives concrete per-parameter usage rules: set content_format when writing markdown, use external_id "whenever a run might be retried," send rehost_images=false to keep original URLs. It does not say when to prefer this over helpcenter_update_article or helpcenter_bulk_create_articles, which is the main missing 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?

Goes well beyond the annotations (which only say it is a non-readonly, non-destructive, non-idempotent, open-world write): it discloses the write-scoped key requirement, the 403 for read-scoped keys, 422 conditions for unknown language or out-of-scope parent_id, the 201 success shape, and the important side effect that categories are created public. That default-visibility note is exactly the kind of non-obvious behavior an agent would otherwise get wrong.

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

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

Front-loads the purpose, then the auth prerequisite, then the workflow rationale, and closes with returns and errors. The Args block largely mirrors the schema, but it is compact and skimmable, and no sentence is wasted on filler.

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

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

With no output schema, the description supplies the return shape and status code, and it covers auth, default visibility, and the two failure modes for a nested-object, 6-parameter mutation tool. An agent has everything needed to call it correctly on the first attempt.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning beyond the schema: every name/description key must be a language enabled on this help center, and parent_id may be omitted or set to 0 for a top-level category. The icon max-length and position ordering notes merely restate the schema, keeping it from a 5.

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

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

States a specific verb and resource ('Create a category in the HelpCenter.io help center') and immediately situates it in the build workflow relative to helpcenter_create_article. An agent can distinguish it from helpcenter_update_category or helpcenter_list_categories without opening any schema.

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

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

Gives explicit sequencing guidance ('create the categories first, then file articles into them with ... category_id') and a clear exclusion: privacy levels cannot be set here and must be changed in the dashboard. It stops short of naming update_category as the alternative for modifying existing categories, so it is clear context rather than full routing.

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

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

Annotations already declare non-read-only, open-world, non-idempotent, non-destructive, but the description adds substantial undisclosed behavior: the returned api_key is shown only once and must be passed as agent_key on every later call, the help center is private/SEO-hidden on a temporary address, and it is deleted after 7 days unless claimed. It also discloses pools and rate limits (60/hour, 300 open, 30 migration requests/day, OpenAI's shared pool in ChatGPT). Minor gap: it does not state whether creation can fail for reasons other than name_blocked/limits, or how errors surface.

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

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

It is front-loaded (purpose, then return values, then lifecycle, then next steps, then limits) and every section is scannable, but it is long for a three-parameter tool and repeats the no-account/no-sign-in point across the title, the opening sentence and the api_key bullet. The bulk is justified by genuinely non-obvious behavior, so it stops short of being verbose padding.

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

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

For a creation tool with no output schema and open-world semantics, the description covers the return payload field by field, the post-creation lifecycle and expiry, the unclaimed-state capacity caps, rate limits, and the handoff path to migration. An agent can run the full flow from this description without guessing.

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 all three parameters are already documented, including constraints like name_blocked and the 'never fetched by this call' note on source_url. The description mostly restates name/source_url/language without adding format or edge-case detail beyond the schema; baseline 3 applies.

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

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

The description opens with a specific verb and resource ('Create a new HelpCenter.io help center for the user, with no account and no sign-in') and pins down the exact scenario: the first step for someone who does not have HelpCenter.io yet. It is clearly distinguished from the sibling that also creates help centers (helpcenter_request_migration), which is named only as the fallback on limits.

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

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

It states when to call (first step, once per help center), what to do next (helpcenter_scan_import for a named set of source platforms, or create_category/create_article/bulk_create_articles with external_id), and when to switch tools (on limit_reached/capacity_reached, use helpcenter_request_migration). Explicit alternatives and exclusions are both present.

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

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

Goes well past the annotations: it discloses gating preconditions, a full catalogue of refusal codes with the reason for each (external_target_forbidden, target_not_found, source_not_redirectable with the one-segment rationale, redirect_loop, too_many_hops), and the upsert behavior that justifies idempotentHint. This is the kind of context the destructiveHint=true annotation cannot convey on its own.

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

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

Front-loads the core action and destructive upsert behavior, then groups prerequisites and refusals into distinct paragraphs. The error-code sentence is long but each clause adds an actionable distinction; minor compression is possible in the Args examples that repeat schema text.

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

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

With no output schema, the description supplies the return shape ({ action: created|updated, redirect }). Combined with prerequisites, refusal taxonomy, and the sibling handoff, an agent has everything needed to invoke this correctly and to interpret failures.

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 already covers path format constraints, so the description is not carrying that burden alone. It still adds meaning the schema lacks: 'to' must be a published (non-draft) page of this help center, and 'from' must be a visitor-reachable path — semantic constraints that the string schema cannot express. Parameter examples largely duplicate the schema's own examples.

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 ('Send an old path of the help center... with a 301') and defines the exact semantics: re-pointing rather than duplicating, and the constraint that it applies only while nothing else answers the path. It is unambiguously distinguishable from helpcenter_bulk_create_redirects, which is named explicitly.

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

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

Gives explicit when-to-use routing ('For many redirects at once, use helpcenter_bulk_create_redirects') and states prerequisites plus the capability_locked failure with a recovery path (helpcenter_get_help_center). Exclusion conditions are enumerated concretely rather than left to inference.

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

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

Annotations already flag destructiveHint=true, but the description adds substantially more: contents are re-filed rather than destroyed, articles are never deleted, articles in multiple categories keep the others, the call fails closed at 'refuse', and it enumerates 403/404/409 conditions. These are non-obvious behavioral guarantees an agent could not infer from the annotations.

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

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

Front-loaded with purpose and the DESTRUCTIVE warning, then cleanly sectioned into Args/Returns/Errors. There is mild redundancy — the opening line and the 'DESTRUCTIVE' line both preview the content-relocation behavior later spelled out — but overall the length is justified by the hazard being described.

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

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

A mutation tool with no output schema, yet the description supplies the response shape (status, on_orphan, articles_moved, children_moved, moved_to) and the full error taxonomy, which is exactly what an agent needs to plan and recover. 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 coverage is 100%, so baseline is 3, and the description still adds value: it defines the tri-state on_orphan behavior in workflow terms and notes the non-obvious edge case that 'reparent' with no parent is equivalent to 'uncategorize'. Only agent_key is left to 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 and resource ('Delete a category from the HelpCenter.io help center') plus the credential scoping ('bound to your API key'). It is immediately distinguishable from create_category, update_category, and list_categories among the siblings.

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

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

Gives clear operational context: fails closed by default with 409, and instructs the agent to 'Read the response's articles_count / children_count, then choose' before escalating on_orphan. It does not name a sibling tool for inspecting the category or suggest update_category/reparenting as an alternative to deletion, so it stops short of full when-not guidance.

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

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

Annotations declare destructive/idempotent/openWorld, but the description adds what those hints cannot: exactly what is destroyed (the path reverts to a 404) and the gating behavior with a named error code and remediation pointer. That is substantive behavioral disclosure beyond 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?

Front-loads the effect, then prerequisites, then a compact Args/Returns block. Each sentence carries distinct information with no filler, and the absence of an output schema makes the Returns line earn its space.

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

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

For a two-parameter destructive tool with no output schema, the description covers the effect, prerequisites, failure mode, parameter provenance, and return shape. An agent has everything needed to decide to call it and interpret the result.

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

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

Schema coverage is 100%, so both parameters are already documented. The description's redirect_id note ('from helpcenter_list_redirects') duplicates the schema text almost verbatim, and agent_key — including its credential-handling warning — is not mentioned at all, so no meaning is added 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 precise verb and resource ('Delete a redirect') and immediately names the consequence — the path falls through to the help center's not-found page. That outcome detail separates it from the creation/listing siblings (create_redirect, bulk_create_redirects, list_redirects) without needing to name 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?

Gives real usage context: the account-state prerequisites (claimed help center, verified email, active plan) and what happens before they are met (capability_locked with the next step, also visible via helpcenter_get_help_center). It does not explicitly exclude alternatives or state when to prefer a different removal tool, so it stops short of a 5.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description goes well beyond them: it discloses that everything inside the help center is destroyed, that the agent key is revoked, that the action is irreversible, the 7-day auto-deletion rule, and the claimed-account guard. It also explains the return contract, including that a 'pending' status means background completion needing no further action.

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

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

Front-loads the destructive action and irreversibility warning, then conditions, then return semantics, then args. Every sentence carries distinct information: the auto-deletion rule and the already_claimed outcome each prevent a specific agent error, so nothing is padding.

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

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

For a two-parameter destructive tool with no output schema, the description covers the mutation scope, irreversibility, the claimed/unclaimed fork, and the shape and meaning of the return value including the 'pending' case. Nothing an agent needs in order to decide and call correctly is missing.

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

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

Schema coverage is 100% and the schema documents both site_id and agent_key thoroughly, including the credential-handling rules. The description's Args section only restates site_id as 'as helpcenter_create_help_center returned it,' which the schema already says, and it omits agent_key entirely. Baseline 3 is appropriate when the schema does all 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 the help center you created) plus the secondary effect (revoke its agent key) and the irreversibility. The scoping word 'unclaimed' in the title combined with the claimed-help-center sentence separates it cleanly from sibling deletes like helpcenter_delete_category and helpcenter_delete_redirect.

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-to-use ('Only when the user asks for it, or when you created it by mistake') and an explicit when-not-to ('no need to clean up after handing over the claim link: an unclaimed help center is deleted by itself 7 days after creation'). It also names the outcome for the claimed case (answers already_claimed, deletes nothing), so the agent can predict behavior before calling.

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?

Although annotations already declare destructiveHint=true and idempotentHint=true, the description adds material context beyond them: the staged copy is deleted outright with no soft-deleted remnant and no undo, the live article is unaffected, staging is scoped per article AND per language, and error 404 covers unknown article, cross-help-center access, or nothing staged. That is exactly the risk profile an agent needs before a destructive call.

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 destructive action and the "read it first" safety advice are front-loaded, and the Args/Returns/Errors blocks are easy to scan. However, the middle paragraph enumerating every public surface where staged content is invisible (sitemap, site search, widget, AI answer path, read endpoints) is background that does not change how the tool is called, and it inflates an otherwise tight definition.

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

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

With three parameters, no output schema, and full schema coverage, the description supplies everything left open: what the call returns ({ status: "success" }), the exact error condition, and the irreversibility of the deletion. Nothing an agent needs in order to call this correctly or warn a user beforehand is missing.

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

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

Schema coverage is 100%, so both article_id and locale are already documented, and the locale wording in the description is nearly verbatim what the schema says. The only added meaning is conceptual: staged versions are held per article and per language, which explains why omitting locale is a broader operation. That is marginal value over 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?

"Throw away staged edits without publishing them" gives a specific verb (throw away) on a specific resource (staged edits) and immediately names the invariant that the live article is untouched. It is cleanly separable from the sibling tools helpcenter_publish_staged_changes, helpcenter_get_staged_changes, and helpcenter_discard_template_changes 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 routes the agent explicitly: use helpcenter_get_staged_changes first "if there is any chance the work is wanted," and frames discard as the deliberate opposite of releasing staged content. It also states the concrete when-not condition (nothing staged → 404), leaving little to inference.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description still adds real value by spelling out that the loss is irreversible, that unpublished Template Editor edits are unrecoverable, and that the live help center is unaffected — the last point is a non-obvious scoping guarantee an agent couldn't derive 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?

The destructive outcome and draft-only scope are front-loaded, followed by irreversibility, a usage gate, and labeled Args/Returns sections. Every sentence earns its place; only the parenthetical about Template Editor edits is slightly padded, so it is efficient without being maximally tight.

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

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

No output schema exists, and the description compensates by stating it returns the reset draft's status, alongside the credential requirement being fully handled in the schema. For a two-parameter destructive tool, this covers what an agent needs, with only the sibling distinction left implicit.

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

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

Schema coverage is 100% and the etag description in the schema is already detailed about stale_draft refusal. The description's 'refuse if the draft changed since you read it' restates the schema's optimistic-lock semantics in condensed form without adding new syntax or edge-case behavior, so baseline 3 applies.

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

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

States a specific verb and scope: discards every unpublished change in the draft and restores the live design, while leaving the live help center untouched. That scopes it apart from publish/restore tools, but it never explicitly separates it from the close sibling helpcenter_discard_staged_changes, so an agent must infer the draft-template vs staged-content distinction.

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

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

Gives a clear when-to condition: 'Only discard when the customer wants to start over,' which functions as both a trigger and a caution against casual use. It stops short of naming alternatives (e.g., restore_template_version for rolling back a published template), so the guidance is directional rather than complete.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior: the response carries has_staged_changes/staged_locales/staged_updated_at, and that a 404 conflates unknown-id with wrong-help-center, which materially changes how an agent should interpret a failure. It does not cover rate limits or pagination (not applicable here).

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

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

Front-loaded with purpose then usage, followed by Returns and Errors sections that earn their space. The explicit 'Args' block largely duplicates the schema and could be trimmed, and 'Read-only.' is redundant with readOnlyHint=true, but overall it is well-organized and readable.

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

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

With no output schema, the description carries the return-value burden and does so concretely (full article with per-language title/content/slug, categories, external_id, staged-changes flags) plus error semantics. For a read tool with a well-documented schema, nothing needed 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 all three parameters are already documented, including the response_format enum semantics and the agent_key credential handling. The description's 'Args' section mostly restates that. Baseline 3 applies because the schema is doing 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 (read) and resource (one article by id) in the first sentence, and explicitly contrasts with the two nearest siblings (helpcenter_list_articles, and implicitly search_articles via the 'after a search' reference). An agent can route correctly without opening the schema.

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

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

Gives an explicit when-to-use condition ('already know the id — after a search, or before editing'), names the alternative it replaces ('instead of paging through helpcenter_list_articles'), and adds a second, non-obvious use case: checking has_staged_changes before a live update to avoid colliding with staged edits.

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, so the safety profile is covered, and the description adds genuinely new behavior: polling semantics, expected status transitions and timing, the capability_locked gating response with a next step for the user, and the fact that the record may take minutes to propagate. That is exactly the context an agent needs to avoid misinterpreting a pending status as failure.

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

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

Front-loaded with the purpose and polling instruction, then preconditions, then a compact Args/Returns block. Slight redundancy in restating the response_format default that the schema already declares, but the Returns section earns its place since no output schema exists.

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

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

With no output schema, the description's inline Returns shape (custom_domain with domain, status, dns_records, certificate, checks, failure, last_checked_at) is necessary and provided. Prerequisites, polling behavior, and the locked-state response are all present for a read-only tool of this complexity.

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

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

Schema description coverage is 100%, so the schema already fully documents agent_key and response_format; the description's 'Args' line merely restates the response_format enum and default. Baseline 3 applies because the schema carries the parameter burden and the description adds nothing beyond it.

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

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

States a specific verb+resource ('Read the help center's custom domain') and then enumerates exactly what is returned: the domain, the DNS record to add, and the status. This is clearly distinguishable from the sibling mutators helpcenter_set_custom_domain and helpcenter_remove_custom_domain.

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

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

Explicitly says to poll it while the user sets up DNS and describes the status progression (pending_dns → verifying → issuing_certificate → live, usually minutes). It also names the preconditions (claimed help center, verified email, active plan) and routes to helpcenter_get_help_center for the capability_locked case, so the when-to-use and when-not-to-use are both covered.

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

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

Well beyond the readOnly/idempotent annotations: it discloses that preview_url expires in one hour and is regenerated on every call, that expires_at is null once claimed or held by a migration, that capability unlocking depends on claim + email verification + plan activation, and that the agent cannot make a help center public. The one point of tension is a fresh preview URL per call alongside idempotentHint=true, but this reflects no side effects on stored data rather than an outright contradiction.

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

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

Front-loaded with purpose, then call timing, then a clearly bulleted breakdown of preview_url, next_step codes and capabilities. Slightly long, with next_step explained both inline and in the 'Returns' header list, but every line carries actionable information.

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

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

With no output schema, the description carries the return-value burden and does it thoroughly, listing every field returned plus structuredContent and decoding next_step codes. Minor gap: it never mentions response_format behavior ('markdown' summary vs 'json' full payload), which only the schema covers.

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 explains site_id, agent_key handling and response_format in detail, including the credential-never-shown rule. The description only restates 'site_id as helpcenter_create_help_center returned it' and adds nothing new about parameters, so the 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?

Opens with a specific verb and resource ('Read the status of the help center you created') and immediately enumerates the exact facets returned: claim state, deletion, capacity, preview link, remaining setup. This is clearly distinguishable from siblings like helpcenter_get_migration_request or helpcenter_get_staged_changes.

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

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

Gives concrete trigger conditions: after writing content, before handing over the claim link, and whenever a tool answers capability_locked. It also names the hand-off path (follow wait_for_migration with helpcenter_get_migration_request), so the agent knows both when to call and what to do next.

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 the description adds real context beyond them: the run is asynchronous, polls should be spaced a minute apart, progress counters include conflicts with local edits and failed images, and error text only appears once a run stops. It does not address the credential requirement, but the schema covers that in depth.

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 and mostly tight, with the polling cadence and read-only status clearly stated. The opening sentence is a long run-on, and the trailing 'limit' sentence is ambiguous enough that it does not fully earn its place.

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

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

With no output schema, the description carries the return-value burden and does so well, naming the plan, selection, progress counters, review queue, and error state. The only gaps are the missing agent_key in the Args block and the unexplained 'limit' reference.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds little on parameters and actually omits agent_key from its Args list despite it being required. The stray sentence 'limit says how much room an unclaimed help center has left' refers to something not present in the input schema, which invites confusion about whether 'limit' is a parameter or a returned field.

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

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

Opens with a specific verb+resource ('Read one import') and immediately enumerates what the read returns: plan, chosen items, run progress, review queue, errors. This is clearly distinguishable from sibling reads like helpcenter_list_imports and helpcenter_get_import_redirect_map.

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 instructs polling this tool until status is completed or failed, and warns that the run reads the source in the background so checks should be a minute apart. It does not name alternatives (e.g., that list_imports should be used to discover imports), but the when-to-use loop is unambiguous.

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

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

Annotations already declare readOnly, idempotent and non-destructive, yet the description still adds non-obvious behavior: pagination at 200 per page, the target_not_found refusal for draft targets, and the fact that an existing 'from' is re-pointed rather than duplicated. Those are exactly the failure and side-effect semantics an agent needs before wiring this into a redirect workflow.

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

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

Front-loads what the map contains and what it is for, then moves to application order and caveats, ending with args and returns. Slightly dense with a couple of rhetorical phrases ('A draft is not a page yet'), but no sentence is redundant.

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

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

For a paginated, prerequisite-gated read tool with no output schema, the description supplies the return shape, page size, default, format options via args, and the operational prerequisites. Nothing an agent needs to call and act on 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%, including a detailed agent_key note, so the schema already carries parameter meaning and baseline 3 applies. The description only echoes the page size and the response shape, adding no new argument semantics beyond what the schema 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?

States a specific verb and resource: for every article and category an import brought in, it returns the old path ('from') and the replacement path ('to'), 200 per page, in the exact shape helpcenter_bulk_create_redirects accepts. That distinguishes it clearly from helpcenter_list_redirects and helpcenter_get_import, which an agent might otherwise confuse it with.

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

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

Explicitly routes the agent: apply page by page with helpcenter_bulk_create_redirects once the user is moving the old address here, and names the prerequisites (claimed help center, verified email, active plan, see helpcenter_get_help_center). It also covers the retry case (drafts are refused with target_not_found until published, then re-apply), which is guidance an agent could not infer.

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

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

Goes well beyond the readOnly/idempotent annotations: the request stays open and its help centers refuse agent-key writes until all are completed or declined, there is a 60-checks-per-hour limit, a wrong id or token returns 'not found' indistinguishably from a nonexistent request, and no agent_key is needed. These are exactly the failure modes and side constraints an agent needs before polling.

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

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

Front-loads the action and the credential source, then a dense but well-organized return-value inventory followed by rate limits and security caveats. The trailing Args list largely duplicates the input schema, which is the only real waste.

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

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

With no output schema, the description carries the full burden and does so: it enumerates status values, expected_by, retry_after, the help_centers array fields, handoff_url semantics, and next_step. An agent has everything needed to interpret the response and act on it.

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

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

Schema description coverage is 100%, so the schema already explains request_id and status_token, including 'never show it to the user'. The description adds the token's 30-day post-request validity and that no agent_key is required, but repeats the schema's provenance note and only restates response_format in the Args block, so it only marginally exceeds the baseline.

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

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

States a specific verb and resource ('Follow a migration request') and names the exact credentials it consumes, which ties it directly to the sibling helpcenter_request_migration that produced them. An agent can distinguish this poll/status tool from the request-creation 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?

Gives concrete polling guidance ('Check at most every retry_after seconds (900)') and the credential lifetime ('the token works until 30 days after the request ends'), which tells the agent when checking is valid and how often. It stops short of naming alternatives or stating when not to call it, but the operational context 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?

Goes well beyond the readOnly/idempotent annotations: it discloses that staged content is invisible to every public surface and to 'this API's read endpoints,' that staging is scoped per article AND per language, and that the returned etag acts as an optimistic lock. Error behavior (404 for unknown, foreign, or nothing staged) is also spelled out.

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

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

Front-loaded with the core action, then structured Args/Returns/Errors sections that are easy to scan. Some sentences are padded, notably the six-item enumeration of public surfaces, but nothing is misleading or redundant with structured fields.

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

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

With no output schema, the description supplies the return shape ({ locale, fields, release_translation, etag, base_signature, updated_at }) and explains that 'fields' holds only what was actually staged. Error semantics and the etag's downstream use complete the picture for an idempotent read tool.

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

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

Schema description coverage is 100%, so the schema already carries article_id, locale, response_format, and the detailed agent_key credential note. The description restates locale and response_format without adding format or syntax detail, so it meets but does not exceed the baseline.

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

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

States a specific verb and resource: 'Read the unpublished staged edits waiting on an article.' This cleanly separates it from helpcenter_get_article, helpcenter_list_article_versions, and helpcenter_stage_article_changes, which an agent could otherwise confuse it with.

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

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

'Call this before staging your own edit, to see whether somebody is already mid-change, and to collect the etag you will pass back as an optimistic lock' gives an explicit trigger and purpose. It stops short of naming the actual alternative reads (get_article, list_article_versions) or when to skip this call.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description earns credit for adding the draft-vs-live boundary, the fact that v2 is editable only, and the 409 template_migration_required and 404 unknown-id errors. It also supplies the concurrency (etag) contract, which no annotation conveys. It stops short of describing default settings trimming effects deeply, which is why this sits at a solid 3 rather than higher.

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

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

Front-loads the one-line purpose, then domain model, then sequencing, then arguments and errors — a clean structure with no wasted framing. It loses a point for restating enum membership in prose ('six page kinds... six regions...') and again in the Args list, which the schema already enumerates.

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

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

With no output schema and a complex nested domain, the description carries the burden of explaining what comes back at each level — the outline's trimmed settings, the theme/brand/meta in full, and the indexes of navigation, scripts, and CSS. It also closes the two failure modes an agent would otherwise hit blind (v1 help centers, unknown ids).

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 the conditional relationships the schema cannot express — which sections require page, region, or id — plus the ordering hint that 'document' is large and parts are preferred. Minor deduction because the Args block partly repeats the enum values already present in 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 precise verb and resource ('Read a help center's current design (the draft)') and immediately scopes the output: status, Template Editor link, page outline, or one part in full. It also distinguishes itself from the family of sibling mutations by naming helpcenter_publish_template as the gate that makes the draft live.

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 sequencing guidance: 'Start here,' then use the outline to plan an edit and only then read the specific component/page/region/CSS block/script in full. It also explains when to carry the returned etag forward (edit tools and publish) so concurrent Template Editor edits cause a refusal rather than a silent overwrite.

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

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

Annotations already cover read-only safety, but the description adds substantial context beyond them: edits target a DRAFT (the same one the dashboard editor opens) and nothing reaches visitors until helpcenter_publish_template; classic v1 help centers return template_migration_required; migration is the owner's dashboard decision; and specific errors 409 and 403 are named. It also notes the guide is generated from the live component registry and is always current.

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

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

Front-loaded with the core purpose and the when-to-use rules, then the domain model, then args, returns and errors. Some material (topic enum explanation, component_types example) restates the schema, and the paragraph on the design model is dense, but every section carries useful information.

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

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

There is no output schema, and the description covers the return format (markdown plus structuredContent, with the overview's extra context), the draft/publish lifecycle, the v1 restriction, and the failure modes. An agent has everything needed to call this correctly on first attempt.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning: it explains what 'overview' actually returns (this help center's languages, FAQ sections, uploaded fonts), that component_types is capped at 8 with examples, and that accepted component values come from the Template Editor and a near-miss guess is refused. Only the agent_key parameter is left entirely to the schema.

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

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

The description states a specific verb and resource ('Learn what can be customized in a help center's design and exactly how') and enumerates the covered domains: the model, edit operations, components, theme tokens, CSS, scripts, navigation. It is clearly the reference/guide tool as distinct from the mutation siblings such as helpcenter_add_template_components or helpcenter_apply_template_theme.

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

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

Explicit when-to-use rules: call with 'overview' before the first design edit in a conversation, and with 'components' plus component_types before adding or configuring a component. It also states the constraint that only v2 help centers can be edited and routes publication to helpcenter_publish_template, giving clear alternatives and 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 cover the safety profile (readOnly, idempotent, non-destructive), so the description wisely spends its space on behavior annotations cannot express: response caps (25,000 chars / 5.0 MB), item-level truncation with truncated:true, body excerpting with content_truncated, and the next-based paging contract including why page+1 with the original limit would skip items. It also names the error conditions (auth, invalid category_id, invalid status/updated_since).

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

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

Front-loaded with purpose and the sibling exclusion, then organized into Args / Returns / Paging / Errors. It is long, and the Args block substantially duplicates the 100%-covered schema, but the volume is justified by 11 parameters and non-obvious truncation/paging semantics; nothing is padding in the Returns and Paging sections.

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 parameters, three enums, and no output schema, the description carries the return-shape burden itself and does so fully — enumeration of item fields, full-object mode, size expectations, and the next-based continuation contract. Little an agent needs in order to call this correctly is left unstated.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning on top: the inclusive bound on updated_since, the de-duplicate-by-id guidance for incremental syncs, the exact field inventory returned when include_content is false, and that order_by supports only 'views'. Some of this mirrors the schema descriptions rather than exceeding them, which keeps it off a 5.

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

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

States a specific verb and resource ('List and browse ... articles') plus its filterable/sortable dimensions, and immediately contrasts itself with the two nearest siblings: helpcenter_search_articles for text search and helpcenter_get_article for full bodies. An agent can pick this tool without opening the schema.

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

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

Gives explicit positive cases (browse a category, most-viewed, full audit, backup, incremental sync) and an explicit exclusion with the alternative named ('rather than to search for specific text (use helpcenter_search_articles for that)'). It also prescribes the two-step read pattern (list without bodies, then get_article), which is the key routing decision here.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: 20-snapshot retention with pruning, history only accruing after staged changes are enabled, empty history being a legitimate non-error state, and a 404 for unknown or cross-help-center articles. These are exactly the traps an agent would otherwise misreport as failures.

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 purpose sentence, then short Args/Returns/Errors blocks — no filler and easy to scan. Minor redundancy in re-stating the response_format default and enum already present in the 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 no output schema, the description supplies the return shape (versions array with id, locale, title, created_at) and the failure mode (404). Combined with the retention and history-accrual caveats, an agent has everything needed to call this and interpret an empty result correctly.

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

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

Schema description coverage is 100%, so article_id and response_format are already fully documented, and the description's Args block largely restates them (including the enum/default). It notably omits agent_key despite that being a required credential parameter, so no added meaning here.

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

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

States a specific verb+resource ('List the archived previous versions of an article') and explains the material mechanism: every publish archives the version it replaced. It also implicitly separates itself from helpcenter_list_template_versions and points at helpcenter_restore_article_version as the consumer of the result.

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

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

The stated purpose ('so a past wording can be restored') plus the handoff note 'Pass a version id to helpcenter_restore_article_version' gives a clear task context and next step. It doesn't explicitly say when not to use it (e.g., use helpcenter_get_article for current content), so it falls short of full when/when-not coverage.

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

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

Annotations already declare read-only/idempotent, and the description goes well beyond them: it explains the 25000-character and 5.0 MB response caps, the truncation flag, and the next-pointer paging contract including the warning that page+1 with the original limit would skip items. It also clarifies that 'position' is only comparable within one parent.

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

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

Front-loaded with purpose, then returns, then paging semantics; every section is skimmable. The Args block partially duplicates the schema's own parameter descriptions, and the paging paragraph is dense, but no sentence is wasted given how unusual the truncation behavior is.

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

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

With no output schema, the description supplies the full response envelope (total, count, page, per_page, total_pages, has_more, next, items) and field list, plus pagination edge cases. An agent has everything needed to call and page 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; the description nonetheless adds operational meaning by explaining how page/limit interact with the server-computed 'next' pointer and that a smaller limit with a later page is the correct follow-up when a page is truncated. The Args list itself mostly restates the schema.

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

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

States a specific verb and resource ("List the categories of the connected HelpCenter.io help center") and names the fields returned (per-language name/description, parent id, icon), which distinguishes it from sibling list tools like helpcenter_list_articles or helpcenter_list_redirects.

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 two concrete use cases: discover valid category ids before creating/filing articles, and render the help center structure. It also points to helpcenter_reorder_categories for reordering, but does not explicitly exclude alternatives such as fetching a single category's details or state when not to use it.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real value beyond them: the 50-item cap, newest-first ordering, inclusion of dashboard-created imports, and the fact that timed-out scan results appear here. It does not discuss pagination or what happens past 50 items, which is the main remaining gap.

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

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

Front-loads the core action and scope, then adds two useful usage notes and a Returns shape. The standalone 'Read-only.' line duplicates the readOnlyHint annotation and is the one piece of low-value text.

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

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

With no output schema, the description compensates by spelling out the returned object's fields (id, platform, status, plan, progress, error, etc.). Combined with ordering, cap, and edge-case notes, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so both parameters are already documented, including the agent_key credential semantics and the response_format enum. The description only restates the response_format default, adding no meaning beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ('List the help center's imports') plus scope details: newest first, capped at 50, with status/plan/progress. It also distinguishes itself from the single-import sibling by describing this as the collection view where dashboard-created and timed-out scan results surface.

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

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

Gives concrete when-to-use context: following/running a source the user connected in the dashboard, and retrieving the result of a helpcenter_scan_import that timed out. It does not explicitly route to helpcenter_get_import for a single import, so it stops short of full alternative 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 readOnly/idempotent/destructive/openWorld, so credit goes to what is added: ordering (newest first), redirect semantics, the capability_locked failure mode and how to recover from it. It does not disclose rate limits or any auth nuance beyond the schema's agent_key text, so 4 rather than 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?

Purpose is front-loaded, followed by prerequisites, args and returns in a predictable order. The Args section largely duplicates a fully documented schema and the standalone 'Read-only.' line repeats the readOnlyHint annotation, which is minor waste but not noise.

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

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

With no output schema, the description supplies the return shape (redirects array fields plus meta pagination), the prerequisite chain and the error state. An agent has everything needed to call it and interpret both success and the locked case.

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 Args block restates the schema wording almost verbatim ('only redirects whose from or to contains this text', '1-100, default 50') and adds no format, interaction or edge-case meaning beyond it.

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

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

States a specific verb and resource ('List the help center's redirects, newest first') and explains what a redirect does (301 from a path that would otherwise 404 to one of its pages). The verb 'list' cleanly separates it from sibling mutations such as helpcenter_create_redirect, helpcenter_bulk_create_redirects and helpcenter_delete_redirect.

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 the real gating condition: the tool only works once the help center is claimed, email verified and a plan activated, otherwise capability_locked is returned with the user's next step. It also cross-references helpcenter_get_help_center for that state. It does not explicitly name alternatives (e.g. create/delete redirect tools) or state when not to call it, keeping it just short of 5.

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

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

Annotations only declare a safe read; the description adds substantial behavior beyond that: edits target a DRAFT shared with the dashboard's Template Editor, nothing reaches visitors until helpcenter_publish_template, and v1 centers reject with template_migration_required. That is exactly the context an agent needs and cannot infer from readOnlyHint.

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

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

Front-loaded with the core action, and the Args/Returns block mirrors the schema cleanly. The middle paragraph enumerating six page kinds, six regions and theme tokens is informative but long for a listing tool and overlaps ground covered by the template guide tools.

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

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

There is no output schema, so the description must explain returns, which it does ("the gallery, or one theme with changed_sections"). Combined with the draft/publish model and the v1 restriction, an agent has everything needed to call this correctly and interpret the result.

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

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

With 100% schema coverage the baseline is 3, and the description does add a little meaning — the current theme is marked, and passing `theme` reveals per-page composition plus which sections applying it would change. However, its `theme` sentence closely restates the schema's own parameter text rather than extending it.

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

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

The opening sentence gives a specific verb and resource plus both modes ("List the ready-made themes a help center can start from, or describe one in full"). It is clearly separable from siblings like helpcenter_get_template and helpcenter_apply_template_theme.

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

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

It states the triggering situation ("when the customer wants a new look, or a starting point to customize from") and routes the follow-up action to helpcenter_apply_template_theme. It also gives a hard precondition — only v2 help centers can be edited, v1 returns template_migration_required and migration is the owner's call — which prevents a whole class of misdirected calls.

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, so safety is covered. The description adds value beyond that by disclosing ordering (newest first), that the live version is flagged, and that each entry carries timestamp, author and publish note — useful return-shape context given there is no output schema.

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

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

The first sentence front-loads what the tool returns, and the second sentence is a single-purpose usage pointer. The 'Args' block repeats what the schema already says about response_format, which is mild waste, but overall it is tight and easy 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?

For a small two-parameter read tool with no output schema, the description adequately conveys what comes back (versions, ordering, live marker, metadata). It does not mention result volume or pagination/truncation behavior, which is the main remaining gap.

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

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

Schema description coverage is 100%, so both parameters are already documented in detail, including the agent_key credential semantics and the response_format enum with default. The description only restates response_format and its default, adding no meaning beyond the schema; baseline 3 applies.

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

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

The description gives a specific verb and resource ('list the help center's published design versions') plus the ordering ('newest first') and the live-version marker, which cleanly separates it from sibling listers such as helpcenter_list_template_themes and helpcenter_list_article_versions.

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

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

It states a concrete use case and names the follow-on tool explicitly: 'Use it to find a version to bring back with helpcenter_restore_template_version.' That is clear routing, though there is no explicit when-not guidance or comparison to a competing list tool.

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

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

The annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the risk profile is pre-supplied. The description nonetheless adds real behavioral context beyond them: nothing reaches visitors until publish, edits land in a draft guarded by an etag (stale_draft), all-or-nothing application with per-position error reporting, and refusal when moving into a synced region whose copies conflict. It does not, however, explain why the operation is marked destructive or what exactly a rollback/discard path looks like.

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 capability, then workflow, then failure modes, then args and returns — a sound structure with no filler sentences. It is dense and repeats some schema text (index/parent_id semantics) and the add_template_components routing twice, which keeps it just short of a 5.

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

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

With no output schema, the description still summarizes the return value (per-entry results with new ids, warnings to relay, draft status and new etag). It covers prerequisites (v2 only, ids from helpcenter_get_template), concurrency (etag), and the publish gate — everything an agent needs before calling a destructive draft mutation.

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

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

Schema coverage is 100%, so the baseline is 3; the description still earns credit for explaining the omitted-field semantics clearly (omitting region or parent_id keeps placement, so {id, index} alone reorders among siblings, parent_id null lifts to region top level) and that index counts positions after the lift. Much of this is mirrored in the schema's parameter descriptions, so it is additive but not wholly new.

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/move) plus resource (template components) and enumerates the destination types: siblings, another region, into a Hero or Container, or out to the region's top level. It also routes the different intent (placing a component on another page) to helpcenter_add_template_components, so it is distinguishable from siblings without opening a schema.

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

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

Gives explicit when-to-use context (editing the v2 design draft that the Template Editor previews) and when-not (classic help centers return template_migration_required; cross-page placement belongs to add_template_components). It also states the workflow expectation: hand the customer the Template Editor link and publish only when asked.

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

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

Beyond the annotations (destructiveHint=true, idempotentHint=false), the description discloses what the call actually does side-effect-wise: archives outgoing live values so it is reversible via helpcenter_list_article_versions, creates a slug redirect, re-indexes, refreshes AI embeddings, and deletes the staged copy. It also details the 409 BASE_CHANGED conflict semantics (per-field, idempotent-aware) and the 422 ARTICLE_UNPUBLISHED case with staged work retention.

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

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

Front-loaded with the core action and scope, then behavior, then the alternative routing, then args and errors. Slightly long with a couple of emphatic asides ('Do not set it reflexively', 'see below'), but nearly every sentence carries operational value.

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

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

For a destructive, non-idempotent mutation with no output schema, the description supplies the return shape, the reversibility path, the conflict and failure modes, and the atomic-multi-article alternative. Nothing an agent needs to invoke it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema for force by explaining the 409 consequence and the decision it implies, and clarifies per-language staging scope. It does not add syntax the schema lacks, so it falls short of a 5.

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

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

States a specific verb and resource ('Apply staged changes to the live article, making them visible to readers') and immediately distinguishes the scope as one article, routing multi-article/atomic needs elsewhere. An agent can tell it apart from helpcenter_discard_staged_changes and helpcenter_create_change_set without opening a schema.

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

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

Explicitly names the alternative for the adjacent case ('To release several articles' staged edits together, or at a set time, group them in a change set... instead of calling this in a loop'), and gives concrete when-to-use guidance for force ('Do not set it reflexively') with three named remedies for the 409 path. Nothing is left to inference.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false; the description adds genuine context beyond them: a version is recorded and restorable later, a fresh draft is started from the published one, changes are immediately visible to every visitor, and only v2 help centers qualify. It also enumerates the failure modes (409 nothing_to_publish, 412 stale_draft) and the exact semantics of the etag guard. It does not state irreversibility timing or permission requirements beyond the agent_key note, keeping it just short of a 5.

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

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

Front-loaded with the effect in sentence one, followed by preconditions, args, returns, and errors in a scannable layout. The middle paragraph anatomizing the template (theme tokens, six page kinds, six regions) is informative but heavier than a publish tool strictly needs, costing a point on tightness.

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

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

For a destructive, non-idempotent, open-world mutation with no output schema, the description covers effect, prerequisites, the reviewed-etag workflow, what is created (version plus fresh draft), the return summary, and both named error codes. Nothing an agent needs to invoke it safely is missing.

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

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

Schema coverage is 100%, so both optional parameters are already documented; the description nonetheless reinforces intent by prescribing passing the etag the customer reviewed and giving a version-history note example ('Brand refresh'). The added value is in the rationale (refuse rather than publish unseen) rather than new syntax, so this sits modestly above the 3 baseline.

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

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

Opens with a concrete verb and effect: 'Put the draft live: every visitor sees the new design from now on', and explicitly claims scope ('the ONE template call that changes the live help center'), which separates it from siblings like helpcenter_update_template_region or helpcenter_publish_staged_changes. The 'exactly the Template Editor's Publish button' anchor makes the mental model unmistakable.

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

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

States both when to use ('Publish only when the customer has asked you to') and the recommended precondition (customer reviewed the draft via the customizer link from helpcenter_get_template), plus the etag safeguard against publishing an unreviewed draft. It also names the blocking condition for v1 help centers (template_migration_required, owner decision in dashboard), which routes the agent away from this tool when it cannot apply.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the mutation profile is known. The description still earns credit by specifying what is actually lost (the domain stops answering) and what survives (the helpcenter.io address), plus the precondition gate and the exact shape of the return. It does not cover reversibility of the domain record or any rate limiting, so it adds real value but not exhaustive 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?

Front-loaded with the effect, then the gating conditions, then the return value — a sensible order with no filler. The 'Returns: { custom_domain } with no domain' line is slightly compressed in phrasing but justifies itself because no output schema exists.

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, open-world mutation with no output schema, the description supplies everything an agent needs: preconditions, the error path and its resolution, the visible effect, and the return value. Nothing material is left for the agent to infer.

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

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

The single agent_key parameter has 100% schema description coverage, including credential handling and secrecy rules, so the schema already does the heavy lifting. The description says nothing additional about the parameter, which matches the baseline of 3 when schema coverage is high.

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 ('Disconnect the help center from its custom domain') and immediately describes the resulting state change: the domain stops answering and the help center falls back to its helpcenter.io address. That consequence framing cleanly separates it from the set_custom_domain and get_custom_domain 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?

Gives an explicit use restriction ('Only when the user asks for it') plus the full prerequisite chain: claimed help center, verified email, active plan. It also names the failure mode (capability_locked) and where the next step can be inspected (helpcenter_get_help_center), so the agent knows both when to call and what to do if it cannot.

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: draft-vs-live semantics, the synced-region effect (removal applies to every page), visitor impact until publish, the v2-only restriction with the template_migration_required response, and the stale_draft refusal when the etag is out of date. It also flags all-or-nothing application, which annotations alone (destructiveHint/idempotentHint) would not convey.

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

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

Front-loads the operation and the draft/publish constraint, then separates arguments and returns into scannable blocks. A few sentences (e.g. the etag note) duplicate schema text and could be trimmed without losing meaning.

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

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

For a destructive mutation with no output schema, the description covers lifecycle (draft vs published), side effects, failure modes, recovery options, and even summarizes the return payload. An agent has everything needed to call it safely and to instruct the customer afterwards.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds the provenance of ids (from helpcenter_get_template) and explains why `page` exists (an unsynced region holding the id on multiple pages). It largely restates the etag and array semantics already documented in the schema, keeping it short of a 5.

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

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

States a specific verb and resource ("Remove components from the draft") plus the key scope detail that nested children go too. It is clearly distinguishable from helpcenter_add_template_components, helpcenter_move_template_components, helpcenter_update_template_components and helpcenter_remove_template_css/script.

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/when-not guidance: edits only the draft, nothing reaches visitors until helpcenter_publish_template, and publish only when the customer asks. It also names the alternatives for reversing the action (helpcenter_add_template_components or helpcenter_discard_template_changes) and the prerequisite source of ids (helpcenter_get_template).

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/idempotentHint, but the description adds real context beyond them: the change only touches a draft, nothing reaches visitors until helpcenter_publish_template, classics return template_migration_required, and stale etags produce stale_draft. It also flags that the Template Editor link should be relayed to the customer for review, which is behavioral guidance no annotation conveys.

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

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

Front-loaded with the action and the alternative, then scope, then args, then return shape — a clean hierarchy. Slight redundancy: the etag/stale_draft behavior appears in both the prose and the schema description, and the publish reminder runs long.

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

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

No output schema exists, and the description covers the return value (what each entry did, warnings, draft status with new etag). Combined with draft/live semantics, error modes, and v2 gating, an agent has everything needed to call this correctly in a multi-step template edit workflow.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by giving provenance for `id` ('Ids come from helpcenter_get_template') and restating the etag lock behavior as a workflow rule. The agent_key credential semantics are left entirely to the schema, which is acceptable given how thorough that schema description is.

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 and resource ('Delete one custom CSS block from the draft') and immediately distinguishes itself from the near-sibling helpcenter_update_template_css by naming the non-destructive alternative. An agent can pick this tool over the ~58 siblings without opening a schema.

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

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

Gives an explicit when-to-use-this-instead condition ('To see the design without it first, switch it off with helpcenter_update_template_css (enabled:false) instead') plus a workflow constraint ('publish only when they ask') and an applicability gate (v2 help centers only). Exclusions and alternatives are both stated.

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

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

Annotations already flag destructiveHint=true, idempotentHint=true and openWorldHint=true, and the description adds real context beyond them: edits hit the draft only, nothing reaches visitors until helpcenter_publish_template, and a stale etag is refused with stale_draft. It does not, however, say whether the delete is reversible (no undo path, unlike restore_template_version for templates) or whether removal affects references elsewhere in the template.

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

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

Front-loaded with the action and the alternative, then scope, prerequisites and return shape — a sensible order. The Args block largely duplicates the schema and could be trimmed, but it is not padded or rambling.

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

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

With no output schema, the description steps in with a Returns line covering new ids, warnings and the new draft etag, plus the advisory to hand the customer the Template Editor link. Missing only the rollback story for an explicitly destructive operation, which is the one thing an agent might still need to ask about.

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 parameters are already documented; the description adds provenance for `id` (comes from helpcenter_get_template) and restates the stale_draft refusal for `etag`. The agent_key credential handling lives in the schema, so the description correctly does not repeat its warnings.

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 concrete verb and resource ("Delete one script or snippet from the draft") and immediately scopes it to the draft rather than the live site. It names the near-sibling helpcenter_update_template_script with (enabled:false) as the non-destructive alternative, so an agent can separate delete from disable 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?

Explicit when-to-use vs when-not: disable instead of deleting if the script should stay but not run, and publish only when the customer asks. It also names the prerequisite read path ("Ids come from helpcenter_get_template") and the v2-only restriction with the exact error a classic help center returns.

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

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

Annotations already declare idempotentHint=true and destructiveHint=true, and the description layers on real value: write-scoped key requirement, the 403/422 failure modes with their meaning, and the atomicity rationale ('no visibly half-sorted tree in between'). It does not explicitly address why the operation is flagged destructive or whether a prior order can be recovered, which keeps it from a 5.

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

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

Front-loaded with the action, then Args/Returns/Errors in scannable blocks; each sentence carries distinct information (scope, alternative, ordering semantics, return shape, error codes) with no filler.

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

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

No output schema exists, and the description compensates by stating the return payload shape, the error codes, the credential requirement, and the sibling-group ordering model — everything needed to call a 2-parameter batch reorder correctly.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds meaning beyond the schema: ordering is per sibling group, top-level sorts against top-level and children against their siblings, so a payload may mix levels. It restates the omit-position behavior that the schema already documents, hence not a 5.

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

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

States a specific verb and resource ('Set the order of categories') plus scope ('bound to your API key'), and explicitly contrasts with repeated helpcenter_update_category calls so the agent can separate it from siblings without opening a schema.

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

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

Explicit routing guidance: prefer this over repeated helpcenter_update_category calls, and a clear exclusion with the alternative named for the case it does not cover ('does not change any category's parent; use helpcenter_update_category's parent_id for that').

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

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

Goes well beyond the annotations: discloses the auth requirement (write-scoped key, 403 otherwise), the partial-write behavior (unlisted articles stay put, unknown ids returned in skipped_article_ids rather than written), the deliberate refusal to touch the sort setting, and the 404 condition. That is exactly the mutation-side-effect disclosure a destructive tool 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?

Front-loaded with the core action, then the critical visibility caveat in caps, then args, returns and errors. Dense but each block carries information; the Args block is the only partly redundant section.

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

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

With no output schema, the description compensates by enumerating the response fields (updated_count, skipped_article_ids, order_visible, article_sort, hint) and the error cases. An agent has everything needed to call it and interpret the result, including the trap where the call succeeds but the order is never displayed.

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 Args section mostly restates what the schema already documents for category_id, articles and position. It does reinforce the omit-position semantics, but adds little genuinely new meaning beyond the structured fields, so baseline 3 applies.

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

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

States a specific verb and resource with scope: 'Set the reading order of the articles inside one category.' That is clearly distinct from the sibling helpcenter_reorder_categories, which operates on categories rather than articles.

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

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

Gives strong contextual guidance: it explains the prerequisite (write-scoped key), the condition under which the result is actually visible ('Custom' article sort), and explicitly states the tool will not change that setting and why. It does not name a sibling tool to use instead, but the domain distinction from reorder_categories is obvious.

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

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

Goes far beyond the destructive/openWorld annotations: discloses the 30-requests-per-day cap, that writes with the help centers' keys are refused during migration while reads still work, that the 7-day deletion clock is paused, that PII (the email) is sent to a third party, and that nothing is emailed automatically. It also explains the external_id in-place replacement behavior, which is a subtle and important 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?

Dense but well-organized: purpose, when-to-use, per-source mechanics, side effects, consent requirement, return fields, rate limit. It is long, but nearly every sentence carries operational information; a small amount of tightening in the returns paragraph would help.

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

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

With no output schema, the description fully enumerates the return fields (request_id, status_token, handoff_url, help_centers, expected_by) and even instructs how to use and conceal the token. Consent, rate limits, and downstream side effects are all covered, so an agent can call this correctly without guessing.

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 cross-parameter meaning the schema cannot: each source becomes one help center, and putting an api_key in a source's agent_key fills an existing help center rather than creating a new one. The external_id/existing-article guidance is extra context not present in the schema.

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

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

States a specific verb and resource up front ('File a migration request: HelpCenter.io moves one or more knowledge bases (up to 50) into HelpCenter.io') including the scope cap and turnaround. This is clearly distinguishable from sibling tools like helpcenter_run_import or helpcenter_create_help_center.

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 four explicit trigger conditions (KB too big, create_help_center returns limit_reached/capacity_reached, scan_import cannot read the source, multiple KBs) and names the alternative tools being superseded. It also explains the fallback path (known platforms auto-migrate, anything else goes to the migration team).

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

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

Adds substantial context beyond the destructive/idempotent annotations: the restore is itself archived so it can be rolled forward again, the change is immediately visible to readers, and it documents the 403 read-scoped-key and 404 unknown/foreign-resource errors. That is exactly the operational detail an agent cannot get from 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?

Front-loaded with the action and its safety profile, then structured Args/Returns/Errors sections. The Args list is somewhat redundant with a 100%-covered schema, but the Returns and Errors lines earn their space.

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, credential-bearing mutation with no output schema, the description covers effect, reversibility, return shape, and failure modes. Nothing an agent needs in order to call it safely is missing.

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

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

Schema coverage is 100% and the schema already documents article_id, version_id, and the credential parameter in detail. The description's Args section largely restates the schema and omits agent_key entirely, so it adds little meaning beyond provenance of version_id.

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

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

States a specific verb and resource ("Roll a live article back to a previously published version") and distinguishes it from siblings like helpcenter_restore_template_version and helpcenter_update_article by naming the article as the target and version history as the source.

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

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

Explicitly says the version id comes from helpcenter_list_article_versions, which routes the agent to the prerequisite tool, and the reader-facing effect clarifies the context of use. It stops short of naming when to use helpcenter_update_article instead of a rollback.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description goes further by naming exactly what is destroyed ('Unpublished draft edits are replaced') and clarifying the blast radius ('does NOT go live until you publish it'). It also discloses the optimistic-lock refusal behavior and the 404 version_not_found error, so an agent knows both the side effects and the failure modes before calling.

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

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

Front-loaded with the core action and the critical 'not live until publish' caveat before any argument detail, and the Args/Returns/Errors block is easy to scan. Minor padding remains in the parenthetical comparison to the Template Editor's one-click revert and the 'so the customer can review it first' aside.

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

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

For a destructive, non-read-only mutation with no output schema, the description supplies the return value ('the draft status') and the documented error code, plus the draft-replacement and non-publishing semantics. Nothing an agent needs in order to invoke this safely is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters in depth, including the etag lock semantics and the agent_key credential handling. The description's Args block largely restates that, adding only a pointer to helpcenter_list_template_versions for version_id, which the schema also mentions. Baseline 3 is appropriate.

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

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

States a precise verb and target: load an earlier published design into the DRAFT, replacing the draft's content. It also distinguishes itself from the publish path ('It does NOT go live until you publish it'), so an agent can tell it apart from helpcenter_publish_template and helpcenter_restore_article_version without opening any schema.

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

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

Gives concrete intent triggers — 'to undo a change, or bring back a previous look' — and points at helpcenter_list_template_versions as the source of the version_id, which is the necessary prerequisite. It stops short of naming the adjacent alternatives (e.g. helpcenter_discard_template_changes for throwing away a draft versus restoring a published version), so the exclusion set is inferred 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 flag destructiveHint=true, idempotentHint=false, and openWorldHint=true, but the description adds substantive context beyond them: execution is asynchronous/background, a re-run updates rather than duplicates prior articles, locally edited articles are preserved and flagged for review, and unclaimed help centers are capped at 500 articles. That last 'kept as it is and flagged' detail materially softens the destructive framing, which an agent could not derive from the annotations alone.

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

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

The core semantics are front-loaded in two short prose sentences followed by an Args line and a Returns line, with no filler. Minor waste: the Args entry merely echoes a parameter the schema fully documents.

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

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

There is no output schema, and the description compensates by stating the return shape ({ import } with status queued or running) plus the polling contract and the domain-level 500-article limit. For a two-parameter async mutation, nothing an agent needs in order to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the agent_key parameter already carries a thorough explanation in the schema, so the baseline applies. The description's Args block only restates import_id as 'number, required' and adds no semantic detail beyond the schema's 'from helpcenter_scan_import or helpcenter_list_imports' phrasing.

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

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

States a specific verb and resource ('Start an import now') and additionally covers the re-run case ('run a finished or failed one again'), which separates it cleanly from helpcenter_choose_import, helpcenter_scan_import, and helpcenter_cancel_import in the sibling list.

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 agent to helpcenter_get_import for polling until status is completed or failed, and names the limit_reached refusal condition. It does not spell out the precondition sequence (scan_import -> choose_import -> run_import), so the agent must infer that from the sibling names, which keeps this below 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?

Goes well beyond the annotations: discloses robots.txt compliance, the 40s server-side budget versus the 25s call wait, that a timed-out scan likely continues and can be found via helpcenter_list_imports, and the destructive-ish side effect that scanning a different address cancels a prior un-run import (consistent with destructiveHint=true). The only gap is that it does not state explicitly that the returned import/plan objects can be very large or what 'limit' means.

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

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

Front-loaded with purpose and the 'Imports nothing yet' caveat, then workflow, then failure modes, then args and return shape. Nearly every sentence carries operational value; slight density in the timeout paragraph keeps it from a 5.

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

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

For a tool with real side effects, a long-running remote fetch, and no output schema, the description supplies the return shape sketch ({ import: { id, platform, importable, status, plan, ... } }) plus the instruction to keep the id. Timeout, credential-refusal, and unsupported-platform outcomes are all anticipated.

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 prose restates the confirm_ownership rule ('not needed while unclaimed; required once claimed') and the 'only send it when the user has said so' guard, but that is largely duplicated in the schema, and the description never mentions agent_key, which the schema covers thoroughly.

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

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

States a specific verb and resource ('Read a public Zendesk Guide, Intercom, ... help center') and immediately bounds the output ('its categories, articles and languages, and where each language lands here'). The clarifying sentence 'Imports nothing yet' separates it decisively from helpcenter_run_import, which is its nearest sibling.

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 the full pipeline explicitly: scan, optionally helpcenter_choose_import, then helpcenter_run_import, then helpcenter_get_import. It also names the fallback for refused sources (helpcenter_request_migration) and the recovery path on timeout (wait ~20s, check helpcenter_list_imports rather than rescanning). When-to-use and when-not-to-use are both covered.

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

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

Goes well past the annotations: it discloses the 25000-character and 5.0 MB response caps, that overflowing pages are truncated with a truncated flag, that bodies are cut to excerpts with content_truncated, and that include_content can make a page several megabytes. It also documents the two error classes (auth, invalid category_id), none of which the readOnlyHint/idempotentHint annotations convey.

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

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

Front-loads purpose and the sibling distinction, then sections Args/Returns/Paging/Errors so an agent can jump to what it needs. It is long, and the include_content and limit/page details duplicate the schema descriptions almost sentence for sentence, which is the main wasted space.

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 open-world search tool with no output schema, the description supplies the full return payload shape ({ total, count, page, per_page, has_more, next, items }), the pagination contract via next, truncation semantics, and error behavior. Nothing essential to calling it correctly is left unstated.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds decision-relevant meaning: why include_content defaults to false (bodies excluded, read via helpcenter_get_article), that limit is capped at 100, and that lang falls back to the site default. It largely restates the include_content schema text rather than extending it, which keeps this below 5.

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

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

States a specific verb and resource (full-text search of help center articles by query string), names the ranking/backend (Meilisearch over titles and content), and explicitly distinguishes the intent from the sibling helpcenter_list_articles. An agent can pick between browsing and searching without opening either schema.

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

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

Gives the selecting condition verbatim ('find the article about X' intents), names the alternative for browsing by category, and prescribes the follow-up workflow: search, then read the best one to three matches with helpcenter_get_article. Exclusions and next steps are both 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?

Goes well beyond the annotations by disclosing the 4-changes-per-month quota, that the old domain stops answering, the no-op case when the domain is unchanged, and the domain_taken refusal. The destructiveHint=true annotation is corroborated rather than merely repeated, and the credential/lifecycle context is spelled out in the schema.

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

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

Front-loaded with the action and its consequence, then prerequisites, then side effects, then args/returns. Dense but purposeful; the multi-clause prerequisite sentence is the only mildly heavy part.

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, open-world mutation with no output schema, it covers preconditions, quota and irreversibility, error outcomes, and the shape of the return ({ custom_domain }). An agent can execute and report back without further discovery.

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 description already states 'no http(s)://, no path' and the www. normalization, so the description's domain note is largely duplicative. No additional syntax or validation detail is added beyond what the schema carries.

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

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

States a specific verb and resource ('Connect the help center to the user's own domain'), and distinguishes itself from the read counterpart by naming helpcenter_get_custom_domain as the follow-up. The DNS/certificate explanation makes the side effect concrete rather than abstract.

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 names the prerequisites (claimed help center, verified email, activated plan) and what to do when they are unmet (read the capability_locked next step). It also gives a negative rule — only set the domain the user asked for — and routes to helpcenter_get_custom_domain afterwards.

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

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

Annotations already flag destructiveHint=true, idempotentHint=true and openWorldHint=true, and the description explains precisely what the destruction means: the whole menu is replaced, so every item to keep must be re-included with its id or its translations are lost, and an empty list clears the menu. It additionally discloses draft-only scope, the stale_draft refusal from the etag check, and the return contents (new ids, warnings, new etag) — well beyond what annotations convey.

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

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

Front-loaded with the operation and its draft-safety constraint, then progressively narrows to link formats and argument details, which is the right order for an agent. It is dense rather than padded, though several href/type details are restated in both prose and the schema, so a bit could be trimmed.

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

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

For a destructive, draft-editing tool with three parameters and no output schema, everything an agent needs is present: prerequisite reads, draft vs published state, failure mode (stale_draft), success contents, and the follow-up publish step. Nothing material about correct invocation is left to inference.

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 real semantics on top: why an id matters (translation survival), the enumerated href forms and the external/type pairing for new tabs, the one-level children limit, the cssClass use case with a concrete "Sign up" button example, and the 30-item cap. Only minor overlap with the schema's own parameter docs keeps it from a 5.

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

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

States a specific verb and resource — "Replace the help center's navigation menu" — and disambiguates it from the many other template-editing siblings by identifying it as the menu every Navigation component draws. It also pins the ordering semantics ("with the items given, in order") and the target (the v2 design draft), so an agent knows exactly which of the ~50 template tools this is.

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-to-use and when-not-to: v2 help centers only (classic ones return template_migration_required), and nothing reaches visitors until helpcenter_publish_template, with the instruction to hand over the Template Editor link and publish only on request. It also routes to the correct preceding tools (helpcenter_get_template for ids, helpcenter_list_categories for category ids), covering the full workflow.

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

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

Annotations only declare the generic profile (mutation, idempotent, destructive, open world); the description supplies the substance: staged content is invisible to render, sitemap, search, widget, AI answer path and read endpoints; staging is keyed per article AND per language; omitted fields retain previously staged values; cross-locale category/visibility must agree or publish fails with 422 naming field and locales. It also discloses the 403 plan-level failure as unfixable by changing the request and the 409/etag conflict workflow.

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