AppPage.net - app websites & store data

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

Beyond the basic annotations, the description provides crucial operational behavioral traits, such as the automatic RSS feed update and the feature enabling logic: 'Turns the changelog on if it's off.' This adds necessary context about state management.

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 highly efficient, combining the core action, a specific complex feature mode, and a state-switching side effect into one concise and readable paragraph.

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 medium complexity and the richness of the schema, the description is fully complete. It explains the primary functional decisions an agent might need to make (manual entry vs. store pull) to execute the tool correctly.

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

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

Although schema coverage is 100%, the description provides critical functional semantics for parameters, specifically detailing the practical meaning and behavioral consequence of setting 'from_store=true' (pull version and notes from the store listing).

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

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

The description clearly states the function: 'Add a release to your site's public changelog.' It specifies the outcome (and RSS feed inclusion), making it extremely clear for an agent.

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?

While it doesn't explicitly compare itself to siblings, it provides a key conditional usage: 'Give version and notes, or from_store=true to add the store listing's current version and What's new.' This defines a specific mode of operation for 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?

Annotations already carry readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description still adds real value with '(live results)' — signaling a fresh network fetch rather than cached data — and with per-store category naming conventions; it does not discuss rate limits, latency or failure behavior.

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

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

Two sentences, zero filler, with the primary capability front-loaded and the store-specific category convention immediately after. Every clause carries actionable information.

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

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

For a read-only, all-optional-parameter list tool with full schema coverage and complete annotations, this is nearly sufficient. The only gap is any hint at the shape of the returned chart entries (rank, app id, price), which matters somewhat since no output schema exists.

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

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

Schema coverage is 100%, so a baseline of 3 applies. The description earns an extra point by explaining that category identifiers are store-specific and giving the two shapes (game_puzzle/health_and_fitness for Google Play vs games_puzzle/photo_and_video for App Store), which disambiguates a 78-value enum that the schema only lists.

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 ('top charts') plus scope (top free/paid/grossing, overall or per category), which separates it cleanly from keyword-oriented siblings like search_apps or single-item get_app. No sibling is named explicitly, so it stops just 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 implied by the enumeration of chart types and the note 'Omit for all apps', which tells the agent how to get the unfiltered list. There is no explicit when-to-use-this-vs-search_apps framing and no stated exclusions or prerequisites, leaving routing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description's added value is the naming constraint (3-14 lowercase letters/digits/hyphens), but it says nothing about what the response looks like, whether results are cached, or behavior on invalid input.

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 zero waste; the domain scope and the purpose come first, followed by the character constraint. Nothing is padded or repeated from the title.

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

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

A single-parameter read-only check with no output schema is adequately covered — the phrasing 'whether ... is free' implies a boolean-style answer. Minor gap: no note on what happens for a malformed or reserved name, but that is small against rich annotations.

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

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

Schema coverage is 100% and the schema already supplies an example mapping. The description still adds real meaning the schema omits: the exact 3-14 character length and allowed character set, which is the validation rule an agent needs to avoid a failed call.

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

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

States a specific verb and resource (check whether a named subdomain is free) and anchors it to the concrete domain apppage.net, plus the intended purpose ('for a new site'). That scoping makes it clearly distinct from the create_site and find_alternatives siblings without opening their schemas.

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

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

'for a new site' implies this is a pre-flight check before creation, which is useful implied usage. But it never explicitly says when to use it versus create_site or, notably, find_alternatives, which likely handles the taken-name case — that routing decision is left to inference.

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

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

Annotations already declare write, open-world, non-idempotent, non-destructive behavior. The description adds genuinely useful context beyond that: which content is auto-filled from the store listing versus which pages start empty (privacy policy, terms, account deletion, support), and that pages must be filled afterward. It stops short of saying what happens on subdomain collision or how long the build takes, keeping it at a 4.

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

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

Three tight sentences with the creation scope front-loaded, followed by the content-completeness caveat and the prerequisite check. No filler, every clause carries information.

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

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

For a write tool with no output schema, the description covers what gets created, what is auto-populated, what is left empty, and the required prior check. A brief note on collision behavior or return value would make it fully complete, but nothing critical to correct invocation is missing.

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

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

Schema coverage is 100%, so all five parameters, including the enum values for store and theme, are already documented. The description restates the subdomain format already present in the schema and adds no meaning for app, store, country, or theme. Baseline 3 is appropriate when structured data does the heavy lifting.

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

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

States a specific verb+resource ('Create a website for a published app') and immediately scopes it to the generated subdomain address and store-listing-sourced content. An agent can distinguish it from set_page, update_site, or refresh_site_from_store without opening a schema.

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

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

Gives explicit prerequisites and alternatives: 'Check the address with check_subdomain first' and 'write them with set_page' for the empty legal pages. This tells the agent both the ordering constraint and which sibling handles the follow-up work.

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 read-only, idempotent, open-world behavior, so the bar is low; the description nonetheless adds that results come from the store's own similar-apps list and are compared on rating, price, installs (Android only) and last update. The Android-only qualifier on installs is a genuinely useful caveat.

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 and the store-source qualifier front-loaded before the example queries. Nothing is redundant or 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 no output schema, the description compensates by indicating what the comparison is based on (rating, price, installs, last update), which hints at returned fields. It does not describe ordering or what happens when no similar apps exist, a minor gap for a simple two-parameter read tool.

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

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

Schema coverage is 100% and both parameters are already documented, including the app_id format examples and the limit range, so the schema does the heavy lifting. The description adds no further meaning about app_id format or limit behavior, matching the baseline 3.

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

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

States a specific verb and resource ("List apps similar to a given app") and pins down the data source as "the store's similar-apps list," which separates it from a generic search. It stops short of naming the sibling search_apps/get_app, so sibling discrimination is implicit rather than explicit.

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

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

The examples "apps like X" and "alternatives to X" give a clear trigger context for invocation. There is no explicit when-not guidance or named alternative (e.g., search_apps for keyword discovery), 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?

Adds real context beyond the annotations: it discloses the data provenance (store listing fields), the precedence rule that user answers override them, and that save=true publishes while save=false is review-only. It does not state that publishing overwrites an existing page or whether that is reversible, which matters 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?

Front-loads what the tool does in the first clause and keeps every sentence informational; nothing is filler. However, the middle sentence packs provenance, a long field list, and the override rule into one dense run-on that is harder to parse than it needs to be.

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 4-parameter tool with a large nested answers object and no output schema, the description covers template scope, input provenance, override precedence, the review path, and the pre-generation interview. The remaining gap (what a saved page returns) is minor for a page-generation tool whose result is the page itself.

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

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

Schema coverage is 100%, so the schema already documents site, page, save, and the answers object, establishing a baseline of 3. The description adds one genuinely new semantic rule ('your answers override them' for store-listing-derived values) plus the pre-generation question list, but offers no syntax or format detail the schema lacks.

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

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

Names a specific verb and resource ('Make one of your site's pages from AppPage.net's templates') and enumerates the page genres the enum offers. It also explicitly distinguishes itself from the sibling set_page, so an agent can route 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 an explicit preference rule ('Prefer this to writing a page yourself with set_page'), a pre-flight instruction to ask the user about things the store listing can't supply, and a review-only path via save=false. When-to-use, when-to-ask, and the alternative are all stated.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), so the description's added value is its disclosure of the return payload — developer contact info, ratings, installs, price, version, size, dates, description — with a genuine platform split (iOS adds star histogram, languages, required iOS version). It adds real context beyond the annotations, though it says nothing about error behaviour or rate limiting for an open-world fetch.

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

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

Front-loaded with the one-line purpose, then two parallel platform-specific sentences. The long comma-separated field lists are dense but each item is informative; the enumeration is doing real work in the absence of an output schema.

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

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

No output schema exists, and the description compensates well by enumerating what comes back for each store and how to identify the app. What's missing is failure behaviour (invalid/unknown id) and any note on freshness or caching — minor for a read-only single-record lookup.

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

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

With one parameter at 100% schema description coverage, the schema already carries the Android-vs-iOS meaning and both examples. The description largely restates that mapping; it adds the nuance that the returned fields differ by platform, but no new input syntax or constraints.

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 ('Get details of one app') and immediately distinguishes the two input flavours (Android package name vs. numeric App Store id). It doesn't explicitly contrast itself with close siblings like get_app_privacy, get_app_reviews, or get_developer_apps, so an agent must infer that boundary from the names 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 description tells you what identifier to supply per platform, which is practical invocation guidance, but it never says when to reach for this tool versus the sibling review/privacy/developer tools, nor what to do if the app isn't found. Usage is implied rather than stated.

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral context by detailing the returned content structure for each platform, which matters since there is no output schema; it does not cover failure modes (e.g., app not found) or coverage gaps, keeping it from a 5.

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

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

Front-loaded with the core action, then organized by platform in two efficient sentences. Dense but every clause carries return-content 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 one fully documented parameter and no output schema, the description compensates well by enumerating the returned fields for both Android and iOS. Minor gaps remain around error behavior and whether data can be missing for some apps.

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

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

Schema coverage is 100% and the single app_id parameter already documents accepted formats (package name or numeric App Store id). The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get an app's privacy information') and itemizes exactly what is returned per platform (Play data safety, Android permissions, Apple privacy labels). This clearly separates it from general siblings like get_app or get_app_reviews, though it never names those alternatives 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?

Usage is implied by the content list: call this when you need privacy/permission data rather than reviews or general metadata. However, there is no explicit when-to-use/when-not guidance and no reference to the sibling tools an agent should pick instead for adjacent needs.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world, so safety is covered. The description adds genuinely useful behavior beyond that: the platform-dependent shape of returned records (helpful votes, developer reply, review title), which matters because there is no output schema.

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

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

Two sentences, zero filler. The returned-fields inventory is front-loaded and the platform caveat is attached where it is relevant, followed by the use case.

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

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

With no output schema, the description compensates by enumerating return fields and platform differences, which is the main completeness gap a caller would face. Pagination behavior, total counts, and whether reviews can be fetched beyond 30 are unaddressed, keeping it short of a 5.

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% — each of app_id, country, sort, and limit already documents format, enum values, and bounds. The description adds no parameter-level meaning beyond noting which platform a field comes from, 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 (get user reviews of an app) and then enumerates exactly what a review record contains: star rating, date, text, app version. It even documents platform-specific variance (helpful votes and developer reply on Google Play, review title on App Store), which lets an agent distinguish this from siblings like get_app or get_developer_apps 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?

The closing sentence, "Use it to summarize what users like or complain about," gives a clear intended task context. There are no exclusions or named alternative tools, so the agent must infer that app metadata should come from get_app instead, but the positive guidance 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 this as a read-only, idempotent, non-destructive open-world operation. The description adds a non-obvious behavioral detail: for App Store, a developer name is resolved by search, which affects expectations about lookup behavior.

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

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

Two concise sentences, front-loaded with the core action and followed by store-specific identifier guidance. There is no redundant restatement of annotations or schema fields.

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

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

For a read-only listing tool with full schema coverage and safety annotations, the description is nearly complete. Remaining minor gaps, such as pagination behavior and return shape, are implied by the limit parameter and listing nature.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-store semantics: Google Play uses a developer name, while App Store can use developer_id from other tools or a name that triggers a lookup. This meaningfully supplements the schema descriptions.

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

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

The description opens with a specific verb and resource: "List the apps published by one developer." This clearly separates it from siblings like get_app (single app) and search_apps (search), and the store-specific detail reinforces the exact 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 gives explicit guidance on how to identify the developer per store and points to get_app/search_apps for obtaining an App Store developer_id. It does not explicitly state when to prefer this over search_apps, but the context is clear enough for correct selection.

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

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

Annotations already establish that this is a safe, read-only, idempotent operation. The description adds useful behavioral context by specifying what data is returned for each kind and noting a privacy detail: bug reports exclude the sender's email.

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

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

The description is a single, front-loaded sentence that immediately states the action and then efficiently enumerates the two feedback types. Every phrase contributes useful information without repetition.

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

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

For a simple two-parameter read tool with full schema coverage and clear annotations, the description supplies enough detail about the returned feedback types. It does not cover pagination or sorting behavior, but no output schema exists and the core content is adequately explained.

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

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

Schema coverage is 100%, so baseline credit is due, but the description goes further by explaining what 'ideas' and 'reports' actually contain. This adds meaning beyond the enum values in the schema, especially for the default 'ideas' mode.

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 ('Read') and clearly names the resource: user feedback sent through the site. It distinguishes the two modes, feature requests on the feedback board versus bug reports, with enough detail that an agent can tell what the tool retrieves.

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

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

Usage is implied by 'Read what users sent through your site' and the two kind options, but the description does not explicitly state when to use this tool versus alternatives or when not to use it. No sibling tools are named or ruled 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 readOnly, idempotent, non-destructive and closed-world, so safety needs no restating. The description's value-add is that it discloses what comes back (URLs, remote config, open incidents, latest changelog entries, App Links), which matters because no output schema exists, but it says nothing about pagination, limits on 'latest' entries, or what happens for a site with no modules enabled.

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 compact sentence with no filler, and the module enumeration is front-loaded. The trailing run-on of secondary payloads (remote config, incidents, changelog, App Links) makes the sentence slightly hard to parse but it stays short.

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

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

For a single-parameter, closed-world read tool with no output schema, the description compensates by enumerating the returned payloads in reasonable detail. Missing only edge-behavior notes (empty modules, how many changelog entries count as 'latest').

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

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

Schema coverage is 100% and the single 'site' parameter is fully documented with an address-vs-id format hint and a pointer to list_my_sites. The description adds no additional parameter meaning, which is acceptable 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 description is a verb-less noun phrase listing returned contents, so the action (retrieve/read) must be inferred from the title. It does enumerate the module types (feedback board, bug reports, remote config, changelog, etc.), which makes the resource concrete, but the list also blends in remote config, status incidents, changelog entries and App Links that are not obviously 'modules', blurring the tool's actual 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?

There is no statement of when to call this instead of siblings such as get_site, list_my_sites, or the various set_* mutators. The agent must guess that this is the read counterpart to set_module and set_remote_config.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description still earns credit for adding that the return value is HTML — meaningful context that no output schema provides. It stops short of noting behavior when a page has not been set or what happens on invalid site identifiers.

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

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

A single sentence with the verb and scope front-loaded and zero filler. Every element — verb, resource, the four page names — earns its place.

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

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

With only two required params, full schema coverage, and rich annotations, the description needs little more; stating the return type as HTML closes the gap left by the absent output schema. Minor omission: no indication of failure modes for unset pages or unknown sites.

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

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

Schema description coverage is 100%, and the enum values are already enumerated in the schema, so the description's list of pages largely repeats structured data. It adds no guidance on the 'site' parameter (address vs. id) beyond what the schema already documents, so the baseline 3 applies.

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

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

States a specific verb ('Read') and a specific resource ('the current HTML of one of your site's pages'), then enumerates the four allowed pages. It clearly separates itself from set_page (write counterpart) and get_site (site-level metadata), though it never names those siblings 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?

Usage is only implied: 'Read the current HTML' signals inspection, and the enumeration of pages implies this is for retrieving page content. There is no explicit statement of when to prefer this over get_site or when to use set_page instead, and no prerequisites or error conditions are mentioned.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds value beyond that by disclosing the payload contents (plan tier, inclusions, quota usage) and the fact that it is scoped to 'your' account, i.e. an authenticated self-lookup rather than an arbitrary-plan query.

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 compact sentence that front-loads the resource and then lists the three things returned. Nothing is redundant or 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?

For a zero-parameter read tool with no output schema, the description does the necessary work by saying what fields come back. Minor omissions remain, such as whether quota figures are absolute counts vs. percentages, or whether plan entitlements include limits beyond API calls.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly implies no inputs are needed to scope the call.

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

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

Names the specific resource (the caller's AppPage.net plan) and enumerates what the response covers: tier (Free or Pro), entitlements, and today's API limit consumption. That distinguishes it from every sibling, none of which report account plan or quota. The verb is only implied via the name/title rather than stated in the sentence.

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

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

There is no explicit when-to-use statement or named alternative, but the mention of 'today's API limit is used' implies the natural use case of checking remaining quota before making many calls. An agent can infer the trigger, though nothing in the text confirms or excludes scenarios.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety and idempotency are covered. The description adds a useful inventory of what comes back (page fill status, app-ads.txt records), but says nothing about failure modes for unknown sites or data freshness.

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

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

One front-loaded sentence that names the resource first and then the fields returned. Nothing redundant, nothing missing structurally.

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

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

With no output schema, the description carries the return-value burden and mostly does: it lists the key data categories an agent would retrieve. Only the error/not-found behavior and freshness of store-synced fields are left unstated.

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

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

Schema coverage is 100% and the schema itself explains the 'site' value, including the 'habitly' -> habitly.apppage.net mapping and id form. The description adds no parameter detail beyond that, so baseline 3 applies.

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

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

States a specific verb+resource (details of one of your sites) and enumerates the returned fields: app, theme, page URLs, page fill status, app-ads.txt records. It reads clearly as the single-item counterpart to list_my_sites, though it never names that sibling explicitly.

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

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

'one of your sites' implies fetching a known site after list_my_sites, and the schema's reference to 'as list_my_sites returns' reinforces that flow. But there is no explicit when-to-use/when-not guidance and no comparison to siblings like get_page or update_site.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is fully covered. The description adds the useful scoping fact that results are limited to the caller's own account, but says nothing about ordering, pagination, or result size for accounts with many sites.

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

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

One front-loaded sentence that names the action, the scope, and the returned fields with zero filler. Nothing is repeated from the title or annotations.

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

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

With no parameters, no output schema and full annotation coverage, the description carries the remaining burden of telling the agent what comes back, and it does so by listing the per-site fields. Slightly incomplete only in that it doesn't hint at result volume or ordering.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; baseline is 4. The description correctly signals a no-argument call by describing only the output content.

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

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

States a specific verb and resource ('List the AppPage.net sites') and enumerates exactly what each entry contains (address, app, store, theme, pages/app-ads.txt status). This distinguishes it clearly from the single-item get_site and from site-creation/mutation siblings.

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

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

Usage is implied: it is the account-wide inventory, as conveyed by 'in your account'. However, it never explicitly says when to pick this over get_site or update_site, nor are there 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 readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false. The description adds meaningful behavior beyond that: it discloses that posting will turn the status page on if it is off, and that apps reading app-config.json will display it. It does not mention permissions or what the non-idempotent behavior means for repeat posts.

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 purpose front-loaded and no filler. The final sentence about app-config.json adds visibility context but is slightly cryptic and less essential than the first two.

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 four params at full schema coverage and existing annotations, the safety profile is covered. However, for a mutation tool with no output schema, the description does not say what is returned after posting, nor how it relates to the sibling resolve_status_incident, leaving some gaps an agent would benefit from.

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

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

Schema description coverage is 100%, so site, level, title and message are already well documented, including the enum values for level. The description adds no parameter-level detail such as formatting for title/message or the relationship between level and display, so the schema does the heavy lifting.

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

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

States a specific verb and resource ('Post an incident on your site's status page') with examples of incident types. It is clearly distinct from most siblings, but does not mention the closely related resolve_status_incident, so an agent must infer the posting-vs-resolving distinction from the name 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 clear usage context with examples ('e.g. an outage or planned maintenance') and notes the side effect of enabling the status page if it is off. It does not say when NOT to use this tool or route the agent to resolve_status_incident for closing incidents.

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 context beyond annotations: empty store fields preserve current values (partial-update semantics), the fetch reaches an external store (consistent with openWorldHint), and there is a one-per-minute-per-site throttle. It does not say whether failures surface as errors or what happens if the site is already in sync, but the key risks are 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 compact sentences, front-loaded with the action, then the field-preservation rule, then the throttle. No filler.

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

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

For a one-parameter mutation with annotations and no output schema, this covers what is refreshed, what is preserved, and the rate limit. The only gap is whether the response reports which fields actually changed.

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

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

Schema coverage is 100% and the single 'site' parameter is fully documented with accepted address formats and a pointer to list_my_sites. The description adds nothing about the parameter, which is acceptable given the schema does the work.

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

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

States a specific verb ('Re-read ... now') and resource (the site's app metadata from Google Play or the App Store) plus the exact fields affected (name, icon, screenshots, description, what's new). This distinguishes it from update_site, which implies manual field edits.

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 word 'now' and the store-source framing make clear this is the sync-from-store path rather than manual editing, and the rate note ('Once a minute per site') tells the agent when it will fail. It stops short of explicitly naming update_site as the alternative or stating exclusions.

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

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

Since `destructiveHint` is false, the description provides minimal additional behavioral context. It functions primarily to explain the purpose and usage flow rather than disclose complex behavioral traits like rate limits or state transitions beyond what the title suggests.

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

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

The definition is highly efficient, using only two direct sentences. It prioritizes the function and immediately follows with workflow 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?

It is highly complete. By detailing how to find the required ID via sibling tools (`get_modules`), it satisfies the agent's immediate need to correctly structure the 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?

Even with 100% schema coverage, the description adds semantic value by clarifying the `site` parameter with examples of acceptable identifiers and providing a concrete use case for the optional `message` parameter.

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

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

The description clearly identifies the specific action ('Mark an incident... as resolved') and the resource ('status incident'), leaving no doubt about its core function.

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

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

It provides clear procedural guidance by directing the agent to 'get_modules' to list open incidents. This specifies the necessary preceding workflow step to acquire the required `incident_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 already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description still adds useful behavior beyond them: results are live rather than cached, the actual fields returned are enumerated, and each item carries an apppage_url for follow-up 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?

Two sentences, zero padding, with the core purpose and the return summary front-loaded and the sibling routing placed last. 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?

There is no output schema, but the description enumerates the returned fields (ids, titles, developers, ratings, prices, apppage_url), which is exactly what the missing output schema would have supplied. Combined with annotations and a fully documented input schema, nothing an agent needs is missing.

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

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

Schema description coverage is 100% and all four parameters are fully documented in-schema (limit range/default, store enum, country ISO codes). The description only restates the keyword concept and the store selection, adding no syntax or constraint detail on top.

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 ('Search Google Play or App Store apps by keyword') with the scope qualifier 'live results'. It also distinguishes itself from the get_app sibling explicitly, so an agent can route 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?

'Use get_app for details of one app' gives a clear alternative and the condition that selects it. Beyond that one routing rule there is no explicit guidance on when not to use this tool (e.g., known app id vs keyword).

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description adds substantive behavior on top: the file is validated first and nothing is saved if any line errors, and append mode deduplicates by adding only records not already present. It also makes explicit that replace mode overwrites the whole served file, which is exactly the destruction the agent needs to understand.

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 what is written and where, then the record grammar, then the atomic-validation rule, then the mode caveat. Four sentences, each carrying distinct information with no repetition of structured fields.

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

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

For a 3-parameter destructive write with no output schema, the description covers format, validation failure semantics, and mode behavior thoroughly. The only gap is that it never indicates what a successful call returns or confirms, which would be useful given there is no output schema.

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

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

Schema coverage is 100% and the schema already documents site (including the "habitly" short form), mode, and the enum. The description adds genuine meaning beyond that by spelling out the required line format with a concrete example record, which the schema leaves as just "The app-ads.txt lines."

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 — writing the app-ads.txt file served at a concrete URL — and explains what that file is for (ad-network verification against the store listing). An agent can distinguish this from set_page or update_site without opening any schema.

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

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

The context for use is clear (ad networks check this file against the developer website in the store listing), and the mode=append semantics give a clear conditional. It does not, however, name when to prefer append vs replace or point to a sibling such as set_page for non-app-ads.txt 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 flag destructiveHint=true and idempotentHint=false; the description adds real context beyond that by disclosing the preservation rule ('a platform you leave out keeps its file') and the ""-removes-it behaviour for raw JSON. It stops short of saying what happens when both a raw file and the structured ids are supplied, or what a failed write leaves behind.

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 resource being written, then the two modes, then the preservation rule — every clause carries information. The middle sentence is a long run-on that bundles inputs, outputs and formatting, which costs a little readability.

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

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

For a destructive, non-idempotent write with 7 parameters and no output schema, the description covers the modes and the preservation rule but leaves gaps: interaction/precedence between apple_json and ios_app_ids, and the result of the call. Adequate but not fully complete for a mutating tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces format hints (TEAMID.bundle.id, sha256 fingerprints) that already live in the schema, and only marginally adds the either/or relationship between apple_json and ios_app_ids.

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 (write the Universal Links / App Links files under /.well-known/) and names the concrete artifacts (apple-app-site-association, assetlinks.json). This clearly separates it from neighbours like set_app_ads_txt or set_remote_config, which write different files.

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 lays out the two usage modes: supply ios_app_ids / android_package + android_sha256 and the files are built, or pass a whole file via apple_json / android_json. It also states the leave-out rule. It does not route against sibling tools (e.g. set_app_ads_txt) or state prerequisites, so not a 5.

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

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

Beyond the annotations it adds real behavioral context: a DNS record is returned, activation is conditional on record propagation plus certificate issuance, and repeat calls serve as a progress check. It omits failure/timeout behavior and roughly how long issuance takes, which would round out the picture.

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 action, then the return/handoff, then the polling pattern. No filler; each sentence carries a distinct fact.

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

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

With no output schema, the description properly discloses the return value (the DNS record) and the completion condition. It leaves the response shape for pending state and error reporting unspecified, but an agent has enough to call and poll correctly.

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

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

Schema coverage is 100% — both 'site' and 'domain' are documented with examples in the schema, including the site-address-or-id convention. The description's example domain ('www.myapp.com') repeats the schema example and adds no new parameter information, so baseline 3 applies.

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

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

States a specific verb and resource ('serve one of your sites on your own domain') and gives a concrete example plus plan gating. It's unmistakable what the tool does, but it doesn't explicitly contrast with update_site or other site-mutation siblings.

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

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

Clearly conveys the usage flow: call it, add the returned DNS record, and call again with the same domain to poll until the certificate is issued. It doesn't name alternatives or state when not to use it, but the context for invoking it 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 it is a non-read, non-destructive mutation; the description adds the genuinely useful behavioral fact that module settings are kept when toggled off, which is exactly the risk an agent would otherwise have to guess at. It does not explain plan gating, permission requirements, or whether disabling takes the public page offline, so it stops short of full disclosure.

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 the action and object stated first, followed by a compact inline list that earns its space by defining each module. The closing sentence on retained settings is four words and carries an important guarantee.

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

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

For a three-parameter toggle with full schema coverage and no output schema, the definition gives an agent enough to call it correctly and tells it settings survive toggling. Missing is any statement of what a caller gets back or whether the change propagates immediately to the public site, which matters for a live-site mutation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema by explaining what each enum value actually is (feedback = feature request board, remote_config = app-config.json for force updates/maintenance/notices, press = press kit). The enum in the schema carries only bare names, so this gloss is real added meaning for selecting the right module.

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 (turn on/off) and resource (one of the site's extras), then enumerates every module with a one-line gloss so the agent knows exactly what can be toggled. The only gap is that it never distinguishes itself from the set_remote_config sibling, even though 'remote_config' is one of the modules listed here, which could leave an agent unsure which tool configures versus enables that module.

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 when-to-use is implied by the enable/disable semantics and the enabled flag, but nothing is said about checking current state first (get_modules exists as a sibling) or about the relationship with set_remote_config. No exclusions or prerequisites are stated, so the agent must infer the workflow.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds real value beyond them: scripts, forms and event handlers are stripped from the input, and the whole page is replaced (until then the site page may be auto-generated). It doesn't say what happens on failure or whether the page goes live immediately, keeping it from a 5.

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

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

Two sentences, front-loaded with the action and the page list; the parenthetical about stores asking for a deletion page is useful rather than filler. Slightly dense and clause-heavy, but nothing is redundant with 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?

For a destructive write with full annotation coverage and a fully documented schema, the description supplies the missing behavioral and content-quality guidance (sanitization, data-source tool, contact email). Only minor gaps remain, such as whether the site must already exist and when the new page takes effect.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns extra credit by explaining why delete_account matters ('both stores ask for this page when an app has accounts') and stating Markdown is the default format, which the enum description also notes. It adds semantic meaning to the page choices beyond bare enum labels.

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

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

States a specific verb and resource ('Replace one of your site's pages with new content') and then enumerates exactly the four page kinds the enum allows, so an agent knows precisely what this tool does and how it differs from get_page (read) and update_site (site settings). The scope is unambiguous 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 concrete context for correct use: base the content on what the app actually does and collects, consult get_app_privacy for store privacy data, and include a contact email. It never states when-not-to-use or contrasts with update_site/create_site, so it stops short of a 5.

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

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

Annotations already flag destructiveHint=true and non-idempotent, so the bar is lower; the description still adds real value by disclosing partial-update semantics ('Only the fields you pass change') and the destructive mechanism ('pass "" to clear one'), which explains why the tool is marked destructive. It also warns of a side effect ('Turns remote config on') and of end-user impact (apps below the lowest version must update). Missing: what it returns and any plan/permission prerequisite.

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

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

Two sentences, no filler, with the destination URL and field scope front-loaded. The first sentence is dense but each clause maps to a real parameter group; trimming further would lose the clearing and enabling semantics.

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

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

For an 11-parameter mutation with no output schema, the description covers what is changed, how partial updates behave, how to clear a value, and the enabling side effect — enough for an agent to call it correctly. Return-value explanation is not needed since no output schema is advertised and the effect is visible via app-config.json.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes beyond the per-field schema blurbs by grouping the parameters into coherent concepts and explaining the relationship the schema does not ('the lowest supported and latest versions per platform (apps below the lowest must update)'). It also documents the cross-cutting convention that an empty string clears a field, which no single property description states.

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

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

The description states a specific verb and resource ('Change the remote config your app reads from https://{site}/app-config.json') and enumerates the exact fields it governs, which is far more specific than the sibling update_site or set_module. It never names a sibling to disambiguate against, but the resource is distinctive enough that confusion is unlikely.

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

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

Usage is implied by the field list (version gates, update message, maintenance mode, notice) plus the note that the call 'Turns remote config on', but there is no explicit when-to-use/when-not-to-use guidance and no named alternative such as update_site. An agent can infer the trigger but receives no exclusions.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety and repeat-call behavior are covered. The description adds only that the change is scoped to design/theme (not page content), and says nothing about whether the prior theme is replaced or whether the change is applied immediately.

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

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

A single front-loaded sentence with no wasted words. It is efficient but borders on under-specification given that a mutation tool is being described.

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

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

With annotations covering the safety profile and the schema fully documenting both parameters, the description is minimally sufficient to invoke the tool. It leaves open what happens to the site's existing design/content and whether the change is reversible, which a mutation tool should ideally address.

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

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

Schema description coverage is 100%: both 'site' (address or id, per list_my_sites) and 'theme' (enum of theme1–theme8) are fully documented in the schema. The description adds no parameter meaning beyond what the schema provides, so baseline 3 applies.

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

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

Specific verb ('Change') and resource ('design (theme) of one of your sites'), clearly distinct from siblings like get_site, create_site, or set_page. However it offers no explicit differentiation from set_page, which could also alter site appearance.

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 use this versus set_page or refresh_site_from_store, no prerequisites, and no note that the site must already exist. 'One of your sites' only weakly implies the site is pre-existing.

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