WTFM

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

Annotations already flag destructiveHint=true and openWorldHint=true, so safety is partly covered. The description adds genuinely new behavioral context: it refuses to silently change an existing destination, which tells the agent the operation is guarded against accidental rebinding and may fail rather than mutate.

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

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

Two tight sentences with the core action front-loaded and the safety constraint immediately after. Zero 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?

An output schema exists, so return values need not be described. The description covers purpose and the key refusal behavior for a destructive, open-world operation; only minor gaps remain around prerequisites (what 'configured' requires) and consequences of a failed bind.

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

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

Schema coverage is 0%, so the single project_id parameter is undocumented in structured fields. The description compensates only partially, implying project_id is the remote project target but giving no format or constraint detail (the schema itself enforces a numeric pattern).

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

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

States a specific verb (bind) and resource (this configured local workspace to a remote project). Clear enough that an agent can distinguish it from creation siblings like create_project or init, though it does not explicitly name which sibling to prefer.

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

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

Usage is implied: this is the step that associates an already-configured local workspace with a remote project. However, no explicit when-to-use/when-not guidance and no alternatives are named among the many project/workspace siblings (init, create_project, connect_repository).

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the bar is lower; the description still adds real value by specifying what this does NOT do ('does not stop processes or delete files') and by disclosing the conditional requirement that a writing run needs stopped=true. It stops short of stating auth needs or reversibility of the release.

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

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

Three short sentences with zero padding; the core action and its key constraint are front-loaded and every sentence earns its place.

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

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

An output schema exists, so return values need no explanation, and annotations carry the safety profile. The description covers the action, its non-effects, and one prerequisite, but the unexplained run_id/workspace parameters and thin usage guidance leave a small gap.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains the `stopped` flag's role (required true for a writing run) but leaves run_id and workspace entirely undocumented, so it only partially compensates for the coverage gap.

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

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

States a specific verb+resource ('Release a generation run') and immediately clarifies scope with 'Does not stop processes or delete files', which disambiguates it from the 'cancel' connotation and from write-oriented siblings like update_run. It does not, however, explicitly name a sibling or contrast with retry_operation, so it stops short of full differentiation.

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

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

The phrase 'after the host agent has stopped' gives one timing condition and 'A writing run requires stopped=true' adds a conditional prerequisite, but there is no explicit when-not guidance or named alternative (e.g. update_run vs cancel_run). Usage is implied rather than spelled out.

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

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

Annotations already declare non-read-only, open-world, destructive behavior; the description adds substantial context beyond them: local-mode output (Markdown + screenshots, returns a path), idempotent retry after upload failure without regeneration, and post-call handling of the editor link and show_to_user text. It does not explain what a retry actually overwrites or what makes the call destructive, which is a gap given destructiveHint=true.

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

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

The purpose is front-loaded well, but the description runs long and mixes purpose, preconditions, return-value handling, and end-user UI instructions into one block. The imperative handling rules are useful but could be tightened; several clauses repeat the same 'don't infer completion' idea.

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

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

An output schema exists so return values need not be fully specified, yet the description helpfully covers editor-link vs. local-path output and the show_to_user/open_when_ready follow-up. The main incompleteness is the total absence of parameter documentation despite a 0% coverage schema.

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

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

Three parameters with 0% schema description coverage, and the description never mentions run_id, completed, or workspace. It implies a 'run' exists but gives no meaning, format, or source for the identifiers, so the schema-driven baseline of 3 is not met and the description fails to compensate for the coverage gap.

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

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

States a specific verb and resource: finalize and upload this run as a draft, with concrete scope (host writing/validation completed). However, it does not differentiate itself from similarly-named siblings such as supportpages_finalize_article, supportpages_upload_draft, and supportpages_publish_article, so an agent cannot rule those out from the description alone.

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

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

Gives a clear entry condition (after successful host writing and validation) and an explicit exclusion (never call for a partial or interrupted writer), plus a useful clarification that it must still be called even when the writer handshake already delivered the draft. It stops short of naming alternative tools for the finalize/upload/publish stages.

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

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

Annotations only cover safety (readOnlyHint=false, openWorldHint=true, destructiveHint=false); the description adds rich context beyond them: the browser sign-in, consent prompt, project selection, and the explicit negative boundaries ('never approves consent, chooses a repository, uploads local articles or starts generation'). This tells the agent exactly what the tool will and will not do.

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

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

Dense but front-loaded: the alias identity and core action come first, then the step sequence, then the boundaries. Every sentence carries operational information, though the resume/next-step sentences are slightly compressed and introduce the mismatched parameter name.

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

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

For a multi-step interactive tool with a nested resume object and an output schema, the description covers the interaction protocol, re-call semantics, and explicit non-actions well. It loses a point for the next_arguments/resume_arguments inconsistency, which leaves the resume contract ambiguous.

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

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

Schema description coverage is only 14% for 7 parameters, so the description must compensate and largely does not. It mentions project_id and the resume flow, but the resume parameter it references is called 'next_arguments' while the schema defines 'resume_arguments' — a naming mismatch that will confuse an agent, and action, feature, workspace, and article_id are never explained.

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

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

States a specific verb and resource ('connect a repository') and frames itself as a compatibility alias for supportpages_setup_hosted, which an agent can use to distinguish it from the canonical sibling. It is somewhat muddied by 'the original requested hosted action', but the core action is clear.

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

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

Describes the interactive loop explicitly: opens sign-in first, asks which help centre, requests consent, then opens the connection/repair page, and says to call again with next_arguments after each step. It does not, however, say when an agent should prefer this alias over supportpages_setup_hosted, so the alternative-selection rule is left implicit.

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

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

Annotations declare the mutation profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true); the description goes beyond them by disclosing the safe default (draft), the hosted/local execution split, that local responses return an existing prepared writer task, and request_id reuse for recovery. It still says nothing about the destructive aspect the annotation flags.

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

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

Purpose is front-loaded and the six sentences are mostly load-bearing, but there is minor redundancy ('never launch a local writer for a hosted operation' largely restates 'hosted projects run in SupportPages').

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

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

An output schema exists so return values need not be described, and execution-routing plus publish semantics are covered. However, with 9 parameters and near-zero schema coverage, the definition leaves most parameter meaning and sibling routing 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 coverage is only 11% (just request_id), so the description must compensate but largely does not. It clarifies publish semantics and re-explains request_id, but leaves title, workspace, description, article_type, open_when_ready, prefer_background and recommendation_id entirely undocumented in both places.

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

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

States a specific verb+resource ('Create one illustrated article') and adds scope via 'using the permitted execution location.' An agent can tell it creates an article, though it never names how it differs from close siblings like supportpages_prepare_article, supportpages_finalize_article or supportpages_create_video_walkthrough.

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 conditional guidance: hosted vs local execution routing, the default-to-draft rule even with auto-publish enabled, and 'set publish only for an explicit user publication request.' It does not, however, point to any alternative sibling or say when to prefer prepare/finalize flows instead.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description adds only the 'no repository connection needed' precondition and never explains permissions required, whether the project is created remotely, or what side effects accompany a destructive-hinted create; 'local generation' mildly muddies the openWorld signal.

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

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

A single front-loaded sentence with no filler; the verb and resource lead. It is efficient, though the semicolon clause is the only content beyond the bare action.

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

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

An output schema exists so return values needn't be described, and annotations cover the safety profile. However, for a two-required-parameter creation tool with 0% schema description coverage, the description leaves parameter meaning, subdomain rules, and permission prerequisites entirely unaddressed.

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

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

Schema description coverage is 0%, so the description must compensate for the two required parameters, and it names neither 'name' nor 'subdomain'. The parameter names are self-explanatory English and the schema carries patterns/length constraints, but the description adds no meaning whatsoever about them.

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: 'Create a SupportPages.io project', and the qualifier 'for local generation' separates it from hosted-setup siblings like setup_hosted. The clause 'no repository connection is needed' implicitly contrasts with connect_repository, though no sibling is ever named directly.

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

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

'for local generation' and 'no repository connection is needed' imply when this tool fits (local-first workflows that skip repo binding), which is more than nothing. But there is no explicit when-to-use/when-not statement or named alternative (e.g., setup_hosted, connect_repository) to route the agent.

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 real behavior beyond the annotations: the operation is durable/async ('returns a durable operation'), uses project voice/settings, and the output is private until explicitly shared. It does not explain why destructiveHint=true or what state the call affects, but the safety profile is already declared by annotations.

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

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

Three sentences, action front-loaded, with the eligibility condition and privacy behavior following logically. Slightly dense in the trailing 'never publish, share or record locally' clause, but no filler.

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

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

An output schema exists, so return values need not be explained, and annotations carry the safety profile. However, for a 6-parameter mutation tool with 17% schema coverage, the description leaves too much parameter and side-effect context unstated to be fully complete.

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

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

Schema description coverage is only 17% (only request_id documented), so the description must compensate and largely does not. It hints at the article concept via 'eligible article' and at project settings, but open_when_ready, expected_revision, prefer_background and workspace receive no added semantics.

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

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

States a specific verb ('Create') and a precise resource ('hosted video walkthrough'), and narrows scope with the qualifying condition 'for a completed eligible article'. This is cleanly distinguishable from sibling read tools such as supportpages_list_walkthroughs and supportpages_get_walkthrough by verb and from supportpages_create_article by resource.

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 precondition ('a completed eligible article') and a when-not directive ('never publish, share or record locally'). It does not name alternative tools (e.g. get_walkthrough for playback), so it stops short of full when/when-not/alternatives guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds valuable context: soft-delete behavior, retention/browser restoration, and a warning not to recreate the article through upload or retry. "Soft-delete" qualifies the destructive nature rather than contradicting the annotations.

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

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

The description is front-loaded and compact, with three short sentences that each add distinct information. There is no filler or repetition.

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

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

The tool has an output schema and annotations covering the destructive profile, so return values and safety are reasonably covered. However, with 0% schema description coverage, the description should explain all three parameters more fully; the optional workspace and expected_revision usage remain under-documented.

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

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

Schema coverage is 0%, so the description must compensate. It implies the selected article and latest revision for the two required parameters, but it omits the optional workspace parameter and does not explain expected_revision beyond the phrase "latest revision." This is partial compensation, not full coverage.

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

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

The description gives a specific verb and resource: "Soft-delete the selected article." It also distinguishes the action from sibling tools like unpublish_article and update_article by specifying deletion semantics.

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 an explicit when-to-use condition: "Use only when the user requests deletion." However, it does not name alternatives such as unpublish_article for cases where the user wants to hide but retain content.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds one genuinely useful trait beyond that: it operates 'without exposing credentials'. It says nothing about what prerequisites are inspected, whether it fails fast, or what a failure 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?

One sentence, front-loaded with the verb and scope, with the credential-safety clause tagged on without padding. Nothing could be cut 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?

With an output schema present, return values need no explanation, and with zero parameters there is no schema gap to fill. The remaining shortfall is purely the absent when-to-use guidance relative to its many diagnostic/init siblings.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No param-level information is required or missing.

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

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

States a specific verb ('Check') and two concrete resources ('configuration and local generation prerequisites'), so an agent can tell it apart from publish/init siblings. It stops short of explicitly differentiating from the nearest neighbours such as supportpages_get_capabilities or supportpages_get_local_plan.

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

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

No statement of when to run this versus supportpages_init, supportpages_get_capabilities, or supportpages_get_local_plan. The agent must infer from the name alone that this is a pre-flight diagnostic.

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 substantive behavior beyond the annotations: edits to published articles go live immediately, failures are non-destructive to the article and its images, and the repository-connected vs. account-only draft paths behave differently. It does not mention permissions or the background/polling workflow implied by prefer_background and supportpages_get_operation.

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

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

Four tight sentences, each carrying distinct information, with the core action and preconditions front-loaded. Slightly dense but 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?

Covers the core edit contract and failure semantics well, and an output schema exists so return values need no explanation. But for a seven-parameter, destructive, open-world tool with a background-execution flag and get_operation/retry siblings, the absence of any async or long-running guidance is a notable hole.

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

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

Schema description coverage is only 14%, so the description must compensate; it explains the intent of instructions and expected_revision and implies article_id via 'Read it first.' The remaining four parameters (workspace, open_when_ready, prefer_background, and the recovery semantics of request_id beyond its own schema note) get no treatment 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+resource ('Edit an existing article') and qualifies it as instruction-driven rather than a field-level update, which is meaningfully distinct. However, it never distinguishes itself from the close sibling supportpages_update_article, so an agent has to infer which one to reach for.

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 procedural guidance: 'Read it first and supply its current revision,' plus a conditional rule that repository-connected edits must be sent as instructions and never written locally. It stops short of naming an alternative tool or exclusion, which keeps it out of 5 territory.

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

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

Annotations already indicate this is a non-read-only, non-destructive write operation. The description adds meaningful behavioral context beyond that, including the required success condition and the rule against finalizing interrupted generations, though it does not discuss permissions or side effects in more detail.

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

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

The description is three tight sentences with no filler, and the core action is front-loaded. Each sentence adds a distinct operational constraint.

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 finalization tool with an output schema, the description covers the key preconditions, the completed=true constraint, and the interrupted-generation prohibition. The omission of section_id guidance is the main remaining gap.

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

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

Schema coverage is only 25%, with artifact_dir being the sole parameter described in the schema. The description compensates for completed (must be true) and run_id (required for prepared runs), but it says nothing about section_id, leaving one parameter's semantics unexplained.

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

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

The description uses a specific verb ('Snapshot') and resource ('successfully completed article for upload'), making the operation clear. It does not explicitly distinguish itself from siblings such as complete_article or upload_draft, but the purpose is still easy to infer.

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

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

It gives explicit timing conditions: set completed=true only after the full skill pipeline succeeds, or after reviewing an existing finished article. It also states a clear prohibition ('Never finalize interrupted generation') and a prerequisite for prepared runs ('require their run_id').

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

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

Annotations declare destructiveHint=true and openWorldHint=true, and the description usefully adds that it returns a durable operation handle and that suggestions remain pending for review (i.e., no automatic mutation of content). But it never explains what the 'destructive' behavior actually is or where the durable operation is resolved, leaving the highest-risk aspect of the annotations unexplained.

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

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

Three short sentences with the core action front-loaded and constraints following; there is no padding. The phrasing is terse to the point of being elliptical, but every sentence carries an instruction.

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

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

An output schema exists so return values need not be spelled out, but a destructive, open-world tool with three undocumented parameters and no statement of what is analyzed or what the operation produces is under-specified. The description does not close the gaps the schema and annotations leave open.

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

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

Schema coverage is only 25% (just request_id documented); workspace, open_when_ready, and prefer_background have no descriptions anywhere. The description adds nothing about these parameters, so three of four inputs remain opaque and the agent must guess at their meaning and defaults.

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

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

The description states it runs a 'hosted documentation analysis' and returns a durable operation, but never mentions the resource the tool is named for (article gaps) or what kind of analysis it performs. An agent gets the general shape (async hosted analysis producing pending suggestions) but cannot distinguish the specific intent from siblings like suggest_sections or recommend_articles based on the text alone.

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

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

The negatives ('never analyse locally, accept suggestions automatically, or generate articles implicitly') imply this is the hosted-analysis path and that output is advisory-only, which is useful routing context. However, no alternative tool is named and no positive trigger ('use when you want to detect coverage gaps in published docs') is given, so the when-to-use condition remains 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 declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds useful context that content is fetched remotely and that revision/publication state comes back, but says nothing about pagination, caching, auth requirements, or failure modes when the article is missing.

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

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

One sentence, front-loaded with the verb and scope, with no filler. Slightly dense phrasing ('revision and publication state') but nothing extraneous.

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

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

An output schema exists, so return values need not be explained, and annotations cover the read-only nature. What is missing is where article_id comes from (list_articles results?) and how this read differs from preview/list siblings, which matters in a 50+ tool surface.

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

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

Schema description coverage is 0%, so the single parameter article_id is documented only by a numeric-string regex pattern. The description does not clarify the ID's origin or format, leaving a gap, though with only one required parameter the risk is limited.

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 ('an article in the bound project') plus what is returned: remote content, revision and publication state. It clearly separates fetching a single article from list_articles, though it does not explicitly name that 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?

There is no guidance on when to use this instead of supportpages_list_articles, supportpages_preview_article, or supportpages_get_operation, and no prerequisites or error conditions are noted. The agent must infer the use case from the name alone.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is partly given. The description adds genuinely new context that no annotation carries: no job is enqueued and no browser consent prompt is triggered, which directly answers an agent's side-effect concern.

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

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

Two short sentences, front-loaded with the core check and followed by the most decision-relevant caveat. No filler, though the description is terse enough that it foregoes useful detail.

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

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

An output schema exists, so return values need not be explained, and annotations cover read-only safety. However, for a tool with 15 action enum values and two undocumented optional scoping params (workspace, article_id), the description does not explain how those parameters affect the capability result.

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

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

Schema description coverage is 0% across all three parameters, so the schema itself explains nothing. The description never mentions the 'action' enum, 'workspace', or 'article_id' — it only says 'an action' generically, leaving the agent to infer semantics entirely from the enum list.

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: 'Check whether an action can run and return its execution location or next setup step.' An agent can grasp this is a preflight/capability probe rather than the action itself. It does not, however, differentiate itself from setup-oriented siblings like supportpages_doctor or supportpages_init, which could confuse routing.

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

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

Usage is implied ('check whether an action can run' before running it) and the sentence 'No job or browser consent is started' hints this is a safe dry-run. But there is no explicit when-to-use guidance, no when-not, and no named alternative among the ~40 siblings.

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

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

Annotations already declare this a safe read (readOnlyHint=true, destructiveHint=false), so the description's added value is the conditional behavior: a local folder yields writing guidance with no sections, inventory, or capacity. That variance in output depending on folder type is genuinely useful context beyond the annotations. It stops short of noting openWorldHint implications (remote account data, auth needs).

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

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

Two sentences, front-loaded with the verb and the primary payload, with the conditional caveat placed second where it belongs. The first sentence is a dense list but every item is a distinct returned resource, 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?

With annotations covering the safety profile and an output schema covering return shape, the description only needs to convey scope and the local-folder caveat, both of which it does. The one gap is routing: it does not explain why an agent should pick this aggregate call over the narrower sibling tools.

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

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

Zero parameters and 100% schema coverage, so the baseline is 4. The description correctly focuses on what the call returns rather than inventing parameter semantics that do not exist.

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

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

Uses a specific verb ('Fetch') and enumerates the resources returned: writing guidance, sections, article inventory, hosting capacity with billing/management links. An agent can grasp the scope, but the description never distinguishes this aggregate context call from siblings like supportpages_get_capabilities, supportpages_list_sections, or supportpages_list_articles, which appear to return overlapping content.

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

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

The second sentence hints at a usage-relevant condition (local folders return guidance only), but there is no explicit statement of when to call this versus the many sibling list/get tools. Usage is only implied by the name and the aggregated nature of the return.

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 readOnlyHint/openWorldHint annotations it discloses genuinely non-obvious traits: this is a compatibility shim, it deliberately returns no local plan, and related features depend on a web-app repository connection. It stays consistent with the read-only annotations and adds real context about what the call cannot do.

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

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

Three short sentences with no filler, and the key limitation is stated early. The only cost is that the opening sentence's vagueness forces the reader through the rest to understand the tool.

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

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

An output schema exists, so return shape needn't be explained, and the negative case (no local plan) is covered. What remains missing is a plain statement of what a successful call actually yields, which matters for a tool whose name promises a plan it never delivers.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No misleading parameter claims are made.

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

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

It gives a verb and resource ("Read validated local project detection context") but immediately negates its own name by saying it does not expose a local plan, leaving the agent unsure what is actually returned. It is distinguishable from siblings only by the loose label "compatibility tool," not by a stated scope.

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 a concrete alternative ("Run wtfm analyse in the project terminal if analysis is required") and clarifies that sections/recommendations/PR analysis need a repository connection in the web app. However, it never says when an agent should call this tool rather than skipping it, so the positive usage case is only implied.

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

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

Annotations already declare the safe read profile, and the description adds real behavioral context beyond them: it never resubmits work, it recovers the most recent request when operation_id is omitted, and polling is bounded to 20 seconds. Return format and exact wait semantics remain unspecified, but the added context is strong.

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 usage, then a caveat, then recovery behavior. Dense but every sentence adds a distinct constraint. Slightly compressed given multiple clauses per sentence.

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

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

An output schema exists so return values need no explanation, and annotations cover the safety profile. The description covers purpose, timing, exclusions, and recovery, leaving only the workspace parameter and precise wait behavior unaddressed.

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

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

Schema coverage is 0%, so the description must carry parameter meaning. It explains operation_id well (use the saved id, or omit it to recover the most recent request) and indirectly touches wait_ms via 'polling is bounded to 20 seconds,' but says nothing about the workspace parameter. Partial compensation only.

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

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

States a specific verb+resource: 'Check a hosted operation once.' The clause 'it never resubmits work' implicitly distinguishes it from the retry/update siblings, though no sibling is named explicitly. An agent can tell what it reads 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 triggers ('when the user asks how it is going or after a client restart') and an explicit prohibition ('Do not call it on a loop while an operation runs'), plus the reason (the review link shows live progress). Clear when-to and when-not guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces the safety profile with 'Read-only: never publishes, shares or starts generation,' which is meaningful given the tool exposes private review/playback links. It also discloses that transcript is conditional ('when available'). It stops short of noting any auth/visibility constraints on those private links.

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

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

Three tight sentences: purpose and payload first, then the routing rule, then the safety guarantee. Every clause carries information and nothing repeats 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?

An output schema exists, so the return-value enumeration is bonus rather than burden, and the read-only guarantee plus sibling routing covers the behavioral side. The unexplained 'workspace' parameter is the one real hole for an agent trying to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains walkthrough_id only implicitly ('by ID') and never mentions the 'workspace' parameter at all, leaving one of two parameters completely undefined across schema and prose.

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

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

Specific verb ('Read') plus resource ('hosted video walkthrough') and an explicit inventory of what comes back: generation/visibility state, revision, assets, transcript, and private links. It also distinguishes itself from the Writer-generation path and notes it covers externally created videos, so the agent can tell it apart 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?

Explicitly routes the agent: 'Use get_operation for a Writer generation job; this tool also reads videos created outside Writer.' That names the alternative sibling and the condition under which each applies, leaving little to 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?

Annotations only declare readOnly=false, destructive=true, openWorld=true; the description adds substantial context beyond them: the 'local' return state, browser-approval behaviour when a device is not signed in, the fallback approval link plus comparison code, background sign-in completion with supportpages_status for polling, and the 'project_required' response shape.

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?

Despite being a dense multi-sentence paragraph, it is front-loaded with the core action first, then the branch conditions in the order an agent will hit them. It is longer than most definitions but nearly every sentence carries a distinct branch or constraint.

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

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

For a multi-step auth/registration workflow with four optional parameters and an output schema, the description covers the full state machine (local, approval link, project_required), prerequisites, follow-up calls, and safety rules. Nothing an agent needs to invoke it correctly appears 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 already 100%, so the 3 baseline applies, but the description adds genuine meaning: it explains host_local's behavioural consequence (folder becomes hosted while saved files stay in place), workspace's use only 'when discovery is ambiguous', and project_id's role in re-calling the tool.

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

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

The description states a specific compound verb+resource: 'Sign this device in to SupportPages.io if needed and link the current workspace to a help centre.' This distinguishes it from siblings like supportpages_bind_workspace, supportpages_status and supportpages_create_project, which are named as alternatives.

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

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

It gives explicit conditional routing: the host_local=true case means the user asked to sign in; on 'project_required' the agent should ask the user which help centre, then re-call with project_id, or call supportpages_create_project first; and it states a hard prohibition ('Never accept a token in chat or approve for the user').

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

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

Annotations already declare readOnly/openWorld/non-destructive, and the description adds real behavioral context beyond them: the default source routing depends on sign-in/local mode, no prerequisite status/init call is needed, no login should be requested for local listings, and an empty local result does not imply an empty hosted help centre. These are non-obvious traits an agent could not derive 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 purpose, then dense but purposeful behavioral rules; every sentence adds a constraint or caveat. Minor cost: the 'next_cursor as after_id' phrasing mixes an output field name with an input param, slightly obscuring the pagination instruction.

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

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

An output schema exists, so return values need not be explained, and the description covers routing, prerequisites, and the key empty-result caveat. It is nearly complete for a read-only list tool, with only the workspace parameter's role left undocumented.

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

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

Schema coverage is 0%, so the description carries the burden. It clarifies the semantics of source=hosted and source=local and links hosted pagination to after_id, but leaves the 'auto' default only implicitly described and never explains the workspace parameter, so it compensates only partially.

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 existing support articles') and immediately explains the default local-vs-hosted routing behavior, so an agent understands what the tool actually returns. It falls short of 5 because it never names or contrasts the closely-named sibling supportpages_list_local_articles, leaving some ambiguity about which listing tool to pick.

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/when-not guidance: 'Do not call status or init first and do not ask for login for a local listing,' plus conditional selection rules ('Use source=hosted only for an explicitly hosted inventory request, or source=local to inspect local files while signed in'). It even pre-empts a false inference with the empty-local-result caveat, leaving little to 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?

Annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) are consistent with the 'refresh inventory' mutation, and the description adds real value beyond them: no login/network in local mode, network in remote mode, 'preserves local content,' and inclusion of conflicts. It could still say more about what the refresh mutates.

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

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

Three compact sentences front-load the local-mode behavior and then the alternate mode; each sentence carries distinct information with minimal waste. The dual-branch framing is slightly dense but not padded.

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

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

With an output schema present, return values need not be described, and the two operating modes plus content preservation are covered. However, the undocumented workspace parameter and the specifics of what the inventory refresh changes are gaps for a tool with real state-mutating behavior.

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 'workspace' parameter has 0% schema description coverage and is never referenced in the description, so the agent gets no guidance on what it scopes, that it is optional, or what happens when 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?

The description gives a concrete verb+resource ('List current local article files') and clearly lays out two operating modes (local/signed-out vs. linked-project refresh). It is distinguishable from generic siblings like supportpages_list_articles, though the dual behavior makes the primary purpose slightly ambiguous.

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 condition that selects each behavior explicitly: local mode 'when signed out or in local mode' versus 'Otherwise refresh the linked project inventory.' It does not name alternative sibling tools (e.g., supportpages_list_articles), so it stops short of full when-not routing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, covering the safety profile. The word 'accessible' adds a small amount of context about result scoping, but nothing about pagination, ordering, or result size is disclosed.

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

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

A single, front-loaded sentence with no wasted words. It states the resource and scope immediately.

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

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

This is a simple, no-argument read tool with an output schema that carries the return shape, so the description does not need to explain return values. It is nearly complete, lacking only a nudge on when to use it relative to sibling discovery tools.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a 0-param tool is 4. No parameter-level confusion is possible.

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

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

States a specific verb (List) and resource ('SupportPages.io help centres'), and the phrase 'accessible' hints at permission scoping. It is clear enough to distinguish from create_project, but never names or contrasts against sibling list tools such as list_sections or list_articles.

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

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

The description gives no indication of when to call this versus the other list/discovery tools (list_sections, list_articles, get_context), nor any prerequisites or exclusions. Usage must be inferred entirely from the tool name.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description contributes that results are 'persisted' with 'IDs and review state' and that the list is cursor-paginated, but says nothing about ordering, filtering by workspace, or empty-page behavior. Useful but modest added context.

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

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

Two short sentences, zero filler, with the core purpose ('List persisted suggestions with IDs and review state') front-loaded ahead of the pagination note. Efficient, though the pagination sentence could carry a bit more routing 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?

An output schema exists, so return-value shape need not be explained, and annotations cover safety. However, for a tool sitting next to review_recommendations and many other list tools, the omission of workspace semantics and any sibling differentiation leaves it only minimally complete.

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

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

Schema description coverage is 0%, so the description must carry the load. It explains after_id as the pagination cursor for the next page, but the workspace parameter is never mentioned, leaving half the parameters undocumented in both schema and description.

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

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

The description states a specific verb (List) and resource (suggestions) and adds meaningful qualifiers ('persisted', 'with IDs and review state'). It is clear what the tool returns, though it never distinguishes itself from the sibling supportpages_review_recommendations or the other list_* tools.

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

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

The only usage instruction is 'Use after_id to read the next page,' which describes pagination mechanics rather than when to choose this tool. There is no mention of when to use this over supportpages_review_recommendations or of any prerequisite context.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds useful pagination behavior ('read the next page') and indicates the shape of returned items (IDs and review state). With annotations carrying the mutation/auth profile, this is adequate but not rich.

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

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

Two short sentences with the core action front-loaded and no filler. The only waste is the ambiguity introduced by calling them 'suggestions' when the tool is about 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?

An output schema exists, so return values need not be re-explained, and annotations cover safety. The gaps are the undocumented workspace parameter and the failure to position this tool against its numerous sibling list/review tools, which an agent selecting among fifty siblings would need.

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

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

Schema description coverage is 0%, so the description must compensate for both parameters. It explains after_id's pagination role well (beyond the schema's bare pattern), but the 'workspace' parameter is never mentioned, leaving half the parameters undocumented in both schema and description.

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

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

The description gives a specific verb and resource ('List persisted suggestions with IDs and review state'), which is clearer than the terse name alone. However, it names 'suggestions' while the tool is called 'list_sections', creating a resource-label mismatch that could confuse selection. It also does not distinguish itself from siblings such as supportpages_suggest_sections or supportpages_review_sections.

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 only guidance is 'Use after_id to read the next page,' which is pagination mechanics rather than when-to-use guidance. There is no statement of when this list tool should be chosen over supportpages_list_recommendations, supportpages_review_sections, or other list/review siblings, and no exclusions or prerequisites.

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

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

Annotations already declare the safe read-only profile, so the bar is lower. The description adds real behavioral context beyond structured data: it discloses what state is returned (generation/readiness/sharing/article-publication) and, importantly, the non-obvious pagination mechanic ('pass both next_cursor as after_id and through_id').

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

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

Four tight sentences, front-loaded with what it lists, followed by return content, filtering, pagination, and scope exclusion in a sensible order. Minor cost: the pagination sentence is slightly cryptic without parameter names appearing in the schema descriptions.

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

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

An output schema exists, so return-value detail is largely redundant but harmless. For a filtered-list tool with pagination, the description covers scope, filtering, and paging adequately. The unexplained 'workspace' parameter and unnamed siblings leave small gaps.

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

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

Schema description coverage is 0%, so the description must carry the load. It documents article_id (filter to one article) and explains how after_id/through_id are used for pagination, but leaves the 'workspace' parameter completely unaddressed. Partial compensation for a 0%-coverage schema.

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

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

States a specific verb (List) and resource (hosted video walkthroughs) with scope detail ('including videos created in the browser'). The closing 'Does not generate or share videos' routes the agent away from supportpages_create_video_walkthrough, though it never names the sibling explicitly.

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

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

Gives clear context — use to enumerate walkthroughs, optionally scoped by article_id — and provides an exclusion ('Does not generate or share videos'). It stops short of naming the alternative tools (create_video_walkthrough, get_walkthrough) or stating when to prefer a single-get instead of a list.

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 real behavioral context beyond the annotations: it does not execute generation, it may or may not create a preview depending on environment, it returns a URL that must be surfaced before launching the writer, and it honors a saved background/foreground preference. It does not explain why destructiveHint=true is set for what reads as a capacity/preparation step, which leaves a residual question.

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

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

Six sentences that interleave tool behavior with agent-workflow directives ('show that link immediately', 'report started after launch'). The capacity-check constraint is front-loaded, but the mixture of description and orchestration instructions adds bulk without tightening the tool's identity.

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

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

An output schema exists so return values need not be explained, and the plan_limit/local/remote behaviors are covered. Still, for an 8-parameter write-flagged tool with low schema coverage, the absence of any parameter guidance leaves the definition incomplete for correct invocation.

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

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

Schema description coverage is only 38% (3 of 8 params carry descriptions), so the description is expected to compensate and does not. It names no parameters (title, workspace, section_id, etc.) and adds no semantics beyond the generic mention of a 'personal preference' that maps to prefer_background/open_when_ready.

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 concrete behavior: it checks account-wide hosting capacity, prepares a task brief, creates a preview when supported, and returns an editor_url. It distinguishes itself from generation tools by explicitly saying 'This does not execute generation.' However, the leading framing ('Check account-wide article hosting capacity') sits in tension with the name prepare_article, and it never explicitly contrasts itself with siblings like preview_article or create_article.

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

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

Gives an explicit trigger ('Call this before writing content or rendering images') and a clear when-not case ('In a local folder there is no capacity check or preview'). It also specifies terminal behavior on plan_limit ('stop; no writer should launch'). It stops short of naming specific sibling alternatives for the preparation step.

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 only declare it is non-read-only, non-destructive and closed-world; the description adds real information beyond that by stating the preview is self-contained, that no network requests or article scripts execute, and that a file path and URI are returned. This is meaningful sandbox/behavior disclosure that the annotations do not carry. It stops short of noting whether files are overwritten or where the preview is written.

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

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

Two tight sentences with no filler, and the core action leads. The second sentence usefully bundles the return shape with the sandbox guarantees, though it could be split for scannability.

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

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

An output schema exists, so return values needn't be described, and the sandbox behavior is covered. What's missing is workflow context: which article gets previewed, whether the tool must run after prepare/finalize, and whether repeated calls overwrite the previous preview. For a one-parameter tool this is adequate but has an evident 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% for the single required parameter artifact_dir, so the schema already explains it as a workspace-relative article output directory. The description adds nothing about this parameter, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Create a self-contained local preview'), which is more than a restatement of the name. However it never says what is being previewed (the article in a given directory? the current draft?) nor distinguishes itself from nearby tools like supportpages_validate_article, supportpages_prepare_article or supportpages_finalize_article.

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

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

No guidance on when to use this versus validate_article or prepare_article, and no stated prerequisites (e.g. must the article already be prepared or finalized before previewing?). The agent must infer placement in the workflow from the name alone.

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

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

Annotations only cover safety flags (readOnly=false, destructive=false, openWorld=true); the description goes well beyond them by disclosing the browser-approval sign-in flow, the follow-up protocol for authentication_required/project_required responses, the fact that uploads land as drafts, and two non-obvious side effects: the folder switches to hosted generation while local files are preserved.

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?

Seven sentences, but they are front-loaded (purpose, then trigger, then flow, then exclusions) and each carries distinct operational content. The retry/approval guidance and the 'does not make articles publicly visible' caveat are arguably a touch verbose for a description of this length, but no sentence is filler.

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

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

For a mutation tool with an output schema already covering return values, the description supplies everything else an agent needs: when to invoke, the sign-in branch, the two-step list-then-upload pattern, error-response handling, and the side effects on folder state and local files.

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

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

Schema coverage is 75% and the description adds real meaning beyond it: no slugs lists available articles for selection, passing slugs uploads them, and project_id is the chosen help centre that cannot replace an existing destination. The 'workspace' parameter is left unexplained in both places, so it falls just short of full coverage.

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

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

States a specific verb ('host') and resource ('saved local articles on a SupportPages.io help centre'), and explicitly distinguishes itself from the nearest sibling: 'publish_article is the separate public publication action.' An agent can tell this apart from upload_draft and publish_article without opening any schema.

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

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

Gives an explicit trigger ('use only when the user asks to host or publish saved local articles'), a precondition ('after asking whether they want to sign in or create a free account'), a negative case ('Never use automatically after local generation'), and names the alternative public-publish tool. 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 declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so safety framing is partly covered. The description adds real value beyond them: the change is externally visible in a hosted help centre, and it is reversible via the web editor or unpublish_article. It does not mention permission requirements or what happens on a revision mismatch.

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

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

Three tight sentences: what it does, how to undo it and the guard condition, then the addressing rules. Front-loaded, no filler, and the operational constraint (never both identifiers) sits at the end where it is easiest to apply.

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

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

Output schema exists, so return-value explanation is unnecessary, and annotations carry the safety profile. The description covers purpose, reversibility and identifier selection, but a publishing mutation arguably warrants a note on required permissions and on the concurrency semantics implied by expected_revision.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does explain the two mutually exclusive addressing modes: article_id plus current revision versus legacy slug plus uploaded bundle revision, with "never both" disambiguating the slug/article_id choice. It leaves 'workspace' entirely unexplained and does not clarify that expected_revision is mandatory in all cases.

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+object: making an article visible in the hosted help centre, which is a distinct state transition from create/edit/upload. It explicitly names the inverse sibling (unpublish_article), so an agent can separate it from the ~45 other supportpages tools without opening a schema.

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

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

"Use only when the user has instructed publication" is an explicit when-to-use gate rather than vague context, and it points to the unpublish_article escape hatch for the reverse case. The only omission is that it doesn't name prepare_article/finalize_article as the prerequisite funnel, but the targeting guidance itself 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 destructiveHint=true, openWorldHint=true, and readOnlyHint=false, so the safety profile is largely covered. The description usefully adds that the call returns a durable (async, retrievable) operation and that output is gated behind human review. It does not explain, despite destructiveHint=true, what state is modified or what the durability implies for retries/recovery.

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

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

Three short sentences, front-loaded with the core action and immediately followed by the review-gate constraint. No filler, though the final prohibition sentence is a slight grab-bag of three separate rules.

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

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

An output schema exists, so return-value detail is not required. The description does cover the async/durable operation model and the pending-review semantics, which an agent needs. It remains incomplete on the three undocumented parameters and on how this tool relates to its recommendation-oriented siblings.

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

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

Schema coverage is only 25%: only request_id is documented in the schema, and it carries a solid description there. The description says nothing about workspace, open_when_ready, or prefer_background, so three of four parameters have no meaning anywhere. With low coverage the description is expected to compensate, and it does not.

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

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

The description gives a specific verb and resource ('Run hosted documentation analysis and return a durable operation'), and 'Suggestions remain pending for review' implies the recommend-articles behavior. However, it never states outright that it produces article recommendations, and it does not distinguish itself from close siblings like supportpages_suggest_sections, supportpages_find_article_gaps, or supportpages_list_recommendations.

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 prohibitions ('Never analyse locally, accept suggestions automatically or generate articles implicitly') are genuine usage constraints that shape agent behavior. What is missing is positive routing: no statement of when to pick this over find_article_gaps, suggest_sections, or list_recommendations, and no prerequisites or ordering relative to review_recommendations.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true and destructiveHint=true, so the safety profile is largely carried by structured data. The description adds genuinely useful behavioral context beyond that: the flow pauses on a real browser consent form and the agent must 'Never approve the browser form for the user', which is a human-in-the-loop constraint an agent could otherwise violate.

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

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

Three short sentences, front-loaded with the purpose, followed by the retry mechanics and the key prohibition. No filler or restatement of the tool name.

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

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

An output schema exists, so return values need no explanation, and the description covers the consent-then-retry workflow well. However, for a four-parameter tool with zero schema documentation it leaves real gaps: which parameter carries the action, and when workspace/article_id are required.

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

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

Schema description coverage is 0% across four parameters. The description implies 'action' holds the original action to retry and 'scopes' relates to the missing Writer permissions, but it says nothing about 'workspace' or 'article_id' or the enum values. With low coverage the description is expected to compensate and it only partially does.

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 ('Request explicit browser consent for missing Writer permissions') and adds a workflow clause about preserving and retrying the original action. It is clearly distinguishable from siblings like supportpages_publish_article or supportpages_get_capabilities, though it never names an alternative it might be confused 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?

Usage is only implied: the agent must infer that this tool is invoked after another action fails on missing scopes, since 'missing Writer permissions' is the only trigger signal given. There is no explicit when-to-use statement, no when-not-to-use, and no named alternative, but the retry-after-consent instruction does convey the intended call context.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation profile is covered. The description adds genuine behavioral context beyond that: it discloses a multi-step recovery workflow and a mandatory UX step (exposing editor_url before retry), which the agent could not infer from 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 purpose is front-loaded in the opening sentence, and each subsequent sentence adds a distinct procedural or safety requirement with no filler. It is compact and well-ordered, though the phrase 'returned recovery task' is fairly cryptic without further context.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The workflow and exclusion rules are present, but the near-total absence of parameter meaning for a three-parameter mutation leaves the definition incomplete for correct invocation.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet it never explains run_id or workspace. Only 'stopped' is obliquely implied by 'after stopping the previous writer'. This leaves two of three parameters effectively undefined, a significant gap at this coverage level.

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 first sentence gives a specific verb and resource: 'Resume the same partial article after stopping the previous writer.' This clearly distinguishes the resume-after-stop scenario. However, it does not differentiate itself from the sibling supportpages_retry_operation, which sounds highly related, so 4 rather than 5.

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

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

The description supplies a clear precondition ('after stopping the previous writer') and an explicit exclusion ('Never retry a draft the user kept for editing'). It also enforces a procedural step ('Always show its returned editor_url before retrying'). It stops short of naming sibling alternatives like retry_operation, so 4 not 5.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the mutation risk profile is covered. The description adds real behavior beyond them: it reuses operation and target rather than creating new state, rechecks permissions, and explicitly cannot overwrite an old snapshot. That is useful non-obvious context.

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

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

Three dense sentences, front-loaded with the core action, then prerequisites, then the exception case. No filler or restatement of the name.

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

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

Output schema exists so return values need not be explained. The description covers the failure/remediation flow, permission recheck, and the revision-conflict limitation, which is the key correctness hazard. The only gap is the undocumented workspace parameter and no explicit statement of what a successful retry returns.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains expected_attempt well (current attempt from get_operation) and implies operation_id is the reused operation, but workspace is never addressed. It compensates for about two of three parameters at a baseline level.

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 ('Explicitly retry a failed hosted operation') and scopes it against the generic retry semantics by noting it reuses the operation and target. An agent can distinguish it from siblings like supportpages_retry_article or supportpages_get_operation 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 trigger condition ('after fixing its reported prerequisite'), the required input provenance ('Pass the current attempt from get_operation'), and an alternative path for revision conflicts ('require a new request with a freshly read revision'). Strong guidance, though it does not name the sibling tool to use in that conflict case or state when not to retry at all.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the mutation/irreversibility profile is partly covered. The description usefully adds that acceptance has no side effect on onboarding or generation. However, it does not explain the reversibility of a reject decision, permission requirements, or that this is a state-changing call, leaving meaningful behavior gaps.

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

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

Three short sentences, front-loaded with the core action and following with the key constraint and the follow-up tool. No filler; each sentence adds 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?

An output schema exists, so return values need not be described. The description covers purpose and the important no-side-effect caveat, but leaves the three parameters unexplained, which is a notable gap for a state-changing tool with 0% schema coverage.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining id, decision, and workspace. It does not clarify what id refers to (the recommendation id?), that decision must be accept/reject, or what workspace does. The mention of recommendation_id pertains to a different tool (create_article), not this tool's parameters.

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

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

The description states a specific action pair (accept or reject) applied to a single selected suggestion/recommendation. It is clear this is a decision tool rather than a listing tool. It does not explicitly name sibling tools like list_recommendations or recommend_articles to sharpen the boundary, so it stops short of 5.

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

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

It gives useful context: acceptance does not advance onboarding or start generation, and to actually generate an accepted recommendation you use create_article with recommendation_id. That is clear when-to-use routing, though it lacks explicit when-not conditions for reject or workspace scoping.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, and the description adds a genuinely non-obvious behavioral fact: accepting does not start generation or advance onboarding, which prevents an agent from expecting downstream side effects. It does not explain what rejecting destroys or whether the decision is reversible, so the destructive profile remains only partially covered.

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

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

Three short sentences, front-loaded with the core action and then the two most likely agent misreadings (implied side effects, how to actually generate). No filler, though the final sentence's phrasing ('Generate an accepted article recommendation explicitly with create_article and recommendation_id') is slightly tangled.

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

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

An output schema exists so return values need no explanation, and the description covers the key behavioral caveat and hand-off tool. But with 3 parameters at 0% schema coverage and no explanation of what 'id' refers to, an agent lacks enough to confidently map a suggestion to the call.

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

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

Schema description coverage is 0% across 3 parameters, so the description must compensate and largely does not: it never explains what 'id' identifies (a section, a suggestion, or a recommendation) or what 'workspace' scopes. The only parameter-like hint, recommendation_id, is not even a parameter of this tool, and 'decision' is self-explanatory only because of its enum.

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 action and scope: 'Accept or reject one selected suggestion', which gives a concrete verb pair and limits the operation to a single item. However the description never says 'section' despite the tool name review_sections, and the sibling supportpages_review_recommendations plausibly performs the same accept/reject action, so sibling differentiation is left ambiguous.

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 useful when/next-step guidance: it warns that acceptance does not advance onboarding or start generation, and routes the agent to create_article with the recommendation_id when generation is actually wanted. It does not, however, distinguish this tool from review_recommendations, leaving one obvious alternative unaddressed.

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

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

Annotations already declare this is a non-destructive, non-open-world write, but the description adds real value: the setting is device-scoped ('covers every local folder on this device for this API origin'), persists until explicitly reversed, and explicitly does not affect article generation or hosting. That is exactly the kind of scope/persistence/reversibility context annotations cannot convey.

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

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

Three sentences, front-loaded with the verb, each adding a distinct fact (scope, prerequisites, persistence/limits). Slightly dense on colons and clauses but 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?

An output schema exists, so return values need not be explained, and the description covers scope, persistence, and side-effect boundaries for a simple preference toggle. The only real hole is the unexplained 'workspace' parameter.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. It implicitly covers 'enabled' via 'Enable or disable' but never addresses the optional 'workspace' parameter at all, and its claim that the preference is device-wide is in tension with the existence of a workspace argument.

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 (enable/disable) plus a specific resource (hosting reminders shown after an article is saved locally), which an agent can distinguish from siblings like supportpages_set_repository_reminders or supportpages_set_telemetry by name. It stops short of explicitly naming the sibling it is not, so it earns a 4 rather than 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?

'when the user asks' supplies a weak trigger condition, and 'Needs no account or help centre' removes one prerequisite. However, no when-not guidance is given and no alternative is named, so the agent must infer when this is preferable to set_repository_reminders.

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

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

Annotations already establish the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds genuinely useful behavior beyond that: disabling persists 'until explicitly enabled again' and it 'does not affect article generation or publication' — clarifying persistence and non-impact.

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

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

Three tight sentences, front-loaded with the core action and followed by scope and behavioral caveats. Every sentence carries information; no filler or repetition.

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

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

With an output schema present, return values need not be explained, and the annotations plus scope/persistence notes make the tool mostly callable. The notable gap is the unexplained `workspace` parameter and its tension with the 'bound help centre' framing, which an agent cannot resolve from the description alone.

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

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

Schema description coverage is 0%, so the description carries the full burden. It implies the boolean `enabled` via 'Enable or disable', but never explains the `workspace` parameter or its relationship to the apparently 'bound help centre' scope, leaving half the parameters undocumented.

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

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

States a specific verb (enable/disable) and resource (optional repository connection reminders), with the scope ('bound help centre across local checkouts on this device, for this API origin') narrowing it further. It is distinguishable from the sibling supportpages_set_hosting_reminders by naming 'repository connection' rather than hosting, though that contrast is left implicit.

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

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

'when the user asks' gives a trigger condition for invocation. However, no alternatives are named (e.g., set_hosting_reminders or set_telemetry for other reminder classes) and there is no 'when not to use' guidance, so the routing between the several 'set_*reminders' siblings must be 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 declare it is a non-destructive write with no open-world access; the description adds genuinely new context beyond that: the response reports what is sent plus current state, and environment variables (SUPPORTPAGES_TELEMETRY=0, DO_NOT_TRACK=1) can silently override the setting. That override caveat is exactly the kind of behavior an agent must know. It stops short of saying whether the setting persists across sessions.

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

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

Two tight sentences, front-loaded with the action, then the auth note, then the return/override caveat. Every clause carries information an agent needs; 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 one-boolean toggle with an output schema and annotations already present, this covers the action, the trigger, the auth requirement, the return content, and the environment-variable override. 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?

The single required boolean 'enabled' has no schema description (0% coverage), so the description must carry the load — and it does, explicitly framing the argument as 'on or off.' It never uses the parameter name 'enabled' or states a default, which 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?

The description names a concrete verb pair (turn on/off), the exact resource (anonymous usage counts and crash reports), and the scope (this device). It is instantly distinguishable from every sibling, none of which touch telemetry.

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

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

It gives a trigger condition ('when the user asks') and a prerequisite ('Needs no account'), which is more than most siblings offer. It does not name alternatives, but no sibling competes for this function, so the gap is minor.

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

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

With annotations indicating a mutation (readOnlyHint=false) and open-world interaction, the description adds rich behavioral detail: opens browser sign-in first, asks which help centre, requests device consent, opens connection/repair page, and explains the multi-call pattern returning resume_tool and resume_arguments. It also clarifies that it does not perform critical actions like approving consent or choosing a repository.

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

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

The description is front-loaded with the core purpose and follows a logical flow: setup steps, multi-call pattern, return values, and boundaries. It is appropriately sized for a complex orchestration tool, though the list of negatives at the end could be tightened slightly.

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

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

Given the tool's complexity (multi-step, openWorld, mutation) and low schema coverage, the description provides a good process overview and boundary conditions. However, it leaves key parameters (action enum, workspace, article_id) unexplained, and the 'next_arguments' mismatch may mislead. An output schema exists, so return values need not be detailed.

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

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

Schema description coverage is only 17%, so the description must compensate. It mentions project_id and resume_arguments in context, but fails to explain the required action enum values, workspace, article_id, or the nested resume_arguments fields. Additionally, it references 'next_arguments' (not in schema) instead of 'resume_arguments', causing potential confusion.

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 orchestration purpose: 'Sign in or create an account and connect a repository for the original requested hosted action.' It clearly distinguishes itself from siblings by explicitly stating what it does NOT do (approve consent, choose repository, upload articles, start generation), which contrasts with tools like supportpages_connect_repository or supportpages_upload_draft.

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

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

It gives clear when-to-use context: for the original requested hosted action, and after each user step call again with next_arguments. It also lists exclusions ('Never approves consent...'). However, it does not name specific alternative sibling tools for those excluded actions, leaving the agent to infer the replacement.

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, yet the description adds meaningful side-effect boundaries: it will not initiate auth, spawn a browser, mutate bindings, or expose credentials, and it notes the read-only API path is used only 'when configured.' Return values are covered by the output schema, so the omission there is acceptable.

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

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

Two sentences, front-loaded with the capability list followed by the boundary conditions. Slightly dense, but every clause carries information and there is no padding.

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

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

With an output schema present and annotations covering the safety profile, the description only needs to cover behavior and scope, which it does across five reported facets plus the negative boundaries. The absence of routing guidance against sibling diagnostics is the one meaningful 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 run_id and workspace are already documented in the schema, and both are optional. The description adds no syntax, defaulting, or format detail beyond that, so the baseline 3 applies.

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

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

States a specific verb (Check) and enumerates the concrete resource set it reports on: article progress, draft links, signed-in account, browser approval progress, and help-centre access. An agent can tell what it returns without opening the schema. It does not, however, distinguish itself from adjacent diagnostics like supportpages_doctor or supportpages_get_operation.

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

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

The description frames scope through negatives ('Does not start authentication, open a browser, change bindings') which implies this is the passive inspection call, but it never states when to prefer it over supportpages_get_operation, supportpages_get_context, or supportpages_doctor. Usage is inferred rather than explicit.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true. The description adds real context beyond them: the result is a durable (async) operation, suggestions stay pending for review, and implicit acceptance/generation is disallowed. However, it does not explain what the analysis side effect actually touches, which leaves a mild tension with destructiveHint=true.

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

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

Three sentences, front-loaded with the primary action and then the constraints. Efficient and readable, with only mild jargon ('durable operation') that slightly obscures 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?

An output schema exists so return values need not be described, and annotations cover the safety profile, but three of four parameters remain undocumented and the description never clarifies the analysis' effect on hosted content. Adequate but with clear gaps.

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

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

Schema description coverage is only 25% (just request_id). The description says nothing about workspace, open_when_ready or prefer_background, so it fails to compensate for the documented-parameter gap on a 4-parameter tool.

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

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

States an action ('Run hosted documentation analysis') and a return ('a durable operation'), but the phrasing is abstract and never maps cleanly onto 'suggest sections'. It does not differentiate from siblings such as supportpages_find_article_gaps, supportpages_recommend_articles or supportpages_list_recommendations, so the agent cannot confidently tell what unique purpose this serves.

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

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

There is no explicit 'use this when...' or named alternative. The prohibition ('Never analyse locally, accept suggestions automatically or generate articles implicitly') is a behavioral constraint rather than routing guidance, and no sibling is referenced to disambiguate it from the recommend/gap tools.

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

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

Annotations give readOnlyHint=false, openWorldHint=true, destructiveHint=false, and the description adds real context beyond them: it preserves local content and upload baselines, clarifies missing walkthroughs are 'unavailable, not confirmed deletion tombstones,' and forbids automatic recreation of deleted resources. This meaningfully fills in the mutation and safety 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?

Four tight sentences front-load the main action and every clause carries information (scope, preservation, tombstone semantics, conflict handling). Slightly dense but no filler.

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

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

An output schema exists so return values need no explanation, and the description covers the behavioral subtleties of a sync/destructive-adjacent operation well. The main gap is the undocumented workspace parameter and the absence of routing guidance relative to siblings.

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

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

Schema coverage is 0% and the lone 'workspace' parameter is undocumented. The description never mentions the workspace selector, so it does not compensate for the schema gap on the only input the agent must reason about.

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-plus-resource: 'Refresh remote project settings, articles and video walkthroughs,' and enumerates the scope (remote-only resources, publication/sharing, review links). It clearly conveys a sync/refresh operation, though it does not name any sibling tool it should be chosen over.

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

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

Usage is only implied ('Refresh...') and the closing guidance ('Review conflicts in the editor; never recreate deleted resources automatically') is procedural rather than a when-to-use/when-not statement. No alternative tool or triggering condition (e.g., vs supportpages_status or supportpages_init) is named.

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 openWorldHint=true, but the description adds meaningful context beyond them: the article is not destroyed outright but retained as a draft, it needs an account plus publish permission (not a repository), and the latest revision should be used. That is genuine behavioral value over the structured hints.

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

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

Three short sentences with no filler, and the core effect (remove from public, keep as draft) is front-loaded. It is appropriately sized for a single-action tool, though somewhat telegraphic.

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

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

An output schema exists, so return values need no explanation. For a destructive mutation tool with annotations covering safety, the description supplies auth requirements, the drafting side effect, and revision guidance; the unexplained workspace parameter is the only notable gap.

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

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

Schema description coverage is 0%, so the schema does not explain any of the three parameters. The description only partially compensates, hinting at expected_revision ('Use the latest revision') while leaving article_id and workspace entirely uninterpreted.

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

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

The description states a specific verb+resource ('Remove an article from the public help centre') and adds the key outcome ('retaining it as a draft'), which distinguishes it from a hard delete. It does not explicitly name sibling tools like supportpages_delete_article or supportpages_publish_article, so routing is implied rather than stated.

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

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

It gives prerequisites ('Requires an account and publish permission, not a repository') but does not state when to choose this over alternatives such as delete_article or publish_article. Usage is implied by the draft-retention behavior, not spelled out.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the mutation/safety profile is known. The description goes well beyond them: it discloses what is preserved (images, publication state), that published changes go live immediately, that repository access and publish permission are required, and conflict-handling behavior ('never overwrite browser changes'). This is rich context, though it could be more explicit about the exact scope of destruction.

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

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

Five sentences, all substantive, front-loaded with the action and prerequisite. No filler, no restating of the name, every clause adds operational value (modes, preservation, auth, immediacy, conflict).

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

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

An output schema exists so return values need no explanation, and the description covers auth, conflict, immediacy, and content modes. It is nearly complete for a destructive mutation tool; the main gap is the undocumented article_id/workspace parameters.

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

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

Schema description coverage is 0%, so the description carries the burden. It meaningfully explains the structured_content vs body/title modes and ties expected_revision to get_article, but it says nothing about article_id or workspace syntax/meaning. Partial compensation for a 6-parameter schema, so a 3 is appropriate.

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

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

States a specific verb (save/update) and resource (article) with a scoping qualifier ('exact content update using the current revision'). It clearly describes the operation. However, it never explicitly distinguishes itself from close siblings like supportpages_edit_article, create_article, or upload_draft, which an agent would want to disambiguate.

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

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

'Using the current revision from get_article' establishes the prerequisite read step, and 'Structured articles use structured_content; Markdown articles use body and optional title' tells the agent which mode to use. 'On conflict read again' gives recovery guidance. Missing explicit 'use this instead of edit_article when...' routing, so it falls short of a 5.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the mutation/safety profile is partially covered. The description genuinely adds context beyond them: the compact acknowledgement + editor link return, the mandatory editor_url display even on failure, the scope limit (cannot mark delivered/published), and the stop-the-writer precondition.

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

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

Four sentences, front-loaded with the core action and immediately followed by the sibling alternative; no filler. Slightly dense but every sentence carries a distinct rule.

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

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

An output schema exists, so return values needn't be explained, yet the description still adds useful behavioral rules (editor_url display, scope limit, precondition). However, with 0% param coverage and 6 parameters, half the calling surface remains unexplained, leaving real gaps for a state-reporting mutation tool.

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

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

Schema description coverage is 0% across 6 parameters, so the description must carry the load. It implies the meaning of the 'event' enum values, but stopped, workspace, host_task_id, and execution_mode are entirely undocumented in both schema and description.

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

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

States a specific verb+resource (report host task events: start, failure, interruption, cancellation) and explicitly names the sibling supportpages_status as the alternative for full run details. An agent can distinguish it from supportpages_status and supportpages_cancel_run 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?

Provides explicit routing guidance ('use supportpages_status for full run details when needed') and a precondition ('Stop the writer before reporting a terminal event'), plus a display rule for editor_url. It stops short of clarifying which event value to use in which situation, but the 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?

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, so the mutation profile is known. The description adds non-obvious behavior the annotations cannot convey: idempotent re-upload and rejection of changes touching published 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?

Three short sentences, no filler, and the core action plus target is front-loaded before the safety and rejection caveats.

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

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

An output schema exists, so return values need no explanation, and the safety/idempotency profile is covered. Still missing: what the 'article bundle' actually is or where it comes from, and how the required slug relates to it — notable for a tool that takes only a slug but claims to upload a bundle.

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

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

Schema description coverage is 0%: the single required 'slug' parameter carries only a pattern and maxLength, with no explanation of what it identifies. The description never mentions the slug at all, so it does not compensate for the gap.

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

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

Specific verb (Upload) plus resource (finalized article bundle) plus target (bound SupportPages.io project) and a state qualifier (unreviewed draft). This clearly separates it from supportpages_publish_article by outcome, though it does not name the sibling explicitly.

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

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

'Repeating an upload is safe' and 'Published-article changes are rejected' give useful operating context, and the draft framing implies this follows finalize/prepare and precedes publish. However, there is no explicit statement of when to choose this over supportpages_finalize_article, supportpages_prepare_article, or supportpages_publish_article.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that by enumerating what is checked and by explicitly clarifying that the operation has no run-finalizing side effect, which is useful for a tool whose name could be confused with a state-changing step. It stops short of describing failure behavior or what a validation result 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?

Two short sentences, zero filler, with the scope of validation front-loaded and the non-finalizing caveat immediately after. Nothing needs trimming.

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

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

For a one-parameter, read-only tool with an output schema and full annotation coverage, the description supplies the essentials: what is validated and that no run state changes. The main omission is workflow placement relative to finalize_article/complete_article, which an agent would have 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?

There is a single parameter (artifact_dir) with 100% schema description coverage, so the schema already explains it. The description adds no syntax, format, or path-resolution detail beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb (validate) and names the three things validated: article schema, image references, and available lint results. It partially distinguishes itself from the finalize/complete siblings via the non-finalizing clause, but never names an alternative directly, so it falls short of a 5.

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

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

Usage is only implied: the sentence 'Validation does not finalize a generation run' signals this is a pre-finalization check rather than a completion step, which hints at where it sits relative to finalize_article/complete_article. There is no explicit when-to-use statement, no named alternative, and no stated prerequisites.

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