Sundogs

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

Beyond the annotations, the description discloses the approximately five-minute expiry, one-time nature, browser-only use by the owner, the checkout:create permission requirement, and that the link can cancel a subscription and shows billing details. These are material operational facts an agent could not infer from the annotations alone.

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

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

The description is front-loaded with the core purpose and then layers in the actionable caveats: owner action, expiry, no-subscription path, and permission gate. Each sentence carries distinct operational 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?

Given the tool has no parameters and no output schema, the description supplies the missing behavioral context: what the agent should do with the result, what the owner must do, how long the link lasts, and what happens for accounts without subscriptions. Nothing needed to invoke or interpret the tool appears absent.

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

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

The tool takes zero parameters, so the schema is not the source of ambiguity. The description correctly implies no arguments are needed. A baseline score of 4 is appropriate because there are no parameters to explain.

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: generate a one-time Stripe customer-portal link for an owner with a subscription. It explicitly separates the subscribed case from the no-subscription case, so the agent can tell what this tool will and will not produce.

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 exactly when to use the tool (owner with a subscription needs to cancel or change a card) and when not to use it (accounts without a subscription get a plain message and no link). It also advises asking for the link only when the owner is ready and calling again for a new one after expiry.

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 read-only, closed-world operation. The description adds important behavior beyond that: the permission requirement, the default short versus detailed response modes, the meaning of an empty actionNeeded, and the presence of release notes and actions per version. It does not describe error behavior or rate limits, but it substantially clarifies what the caller receives.

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, but the description is a dense single paragraph with nested parentheticals that make the return-shape details harder to scan. Most content earns its place, but structure could be improved by separating input sourcing, output modes, and permission requirements.

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

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

There is no output schema, so the description carries the burden of explaining return values. It does this well for changes, actionNeeded, whatsNew, and the effect of detail. It leaves some minor gaps around error conditions and explicit sibling routing, but overall it is complete enough 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 coverage is already 100%, so the baseline is 3. The description adds meaningful context beyond the schema: it explains exactly where to obtain the installed object, clarifies that detail controls both the version list and whatsNew list, and notes that core follows the same actionNeeded behavior.

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 precise question the tool answers: which installed apps have newer versions covered by the site's license, and which are not covered. It names the resource (installed apps and newer versions) and distinguishes the result from a simple version lookup by mentioning coverage and fixes.

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 preconditions: pass installed versions from the site's manifest, and the caller needs download permission. However, it does not explicitly state when to use this versus related siblings like renew_updates, get_download, or get_license, nor does it state when not to use it.

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

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

Adds meaningful behavior beyond the annotations: the auth requirement and its two forms, the fact that a claim accepts the free license and the result reports which version, and that only domain plus app id are persisted. The 'safe to repeat, returns the same result' line largely restates idempotentHint=true, so it is additive but not fully independent of 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?

Purpose is front-loaded in the first clause, and each subsequent sentence carries a distinct fact (auth, idempotency, limitation, optional param). It is six sentences and slightly sprawling, 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 non-destructive, idempotent mutation with no output schema, the description covers the auth path, the repeated-call behavior, the rejected case, and the fact that the response reports the licensed version. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns slightly more by explaining what site_domain is for ('record which site will run it') and clarifying that only the domain and app id are stored. The app/app_id alias pair is explained in the schema rather than the 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 and resource: 'Add a free app (like Forms) to the owner's account', plus the key scope limit 'Paid apps can't be claimed'. That implicitly separates it from checkout/purchase siblings like create_checkout, but no sibling is named explicitly.

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

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

Gives clear preconditions (owner signed in via browser sign-in, or an API key with the download permission) and an exclusion (paid apps cannot be claimed). It does not name an alternative tool to use when the app is paid, so no explicit routing.

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

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

Beyond the annotations (which already flag idempotent, non-destructive, non-read-only), it discloses the key behavioral trait: the owner must open the URL and tick the box themselves and the agent must never pay or tick for them. It also names the required checkout:create permission, explains that a repeated open cart returns the same checkout, and covers the free-code "confirm" state and its $0-but-still-must-open 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?

The purpose is front-loaded and every paragraph carries operational content, but the single dense block packs parenthetical asides and repeats the interval rule that the schema already documents. Slightly tighter separation of the coupon and tester-pass edge cases would improve 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?

There is no output schema, yet the description enumerates the returns (checkout_url, total, what's already owned and not charged twice, companion prices and included apps, the license line to relay) and describes the state transitions an agent must poll for. For a mutating, seven-parameter purchase tool this is complete enough to call correctly without further discovery.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: interval "once" means pay once with 12 months of updates and subscriptions are not sold, unlimited vs reseller scope is spelled out, and coupon is limited to one owner-supplied code with the coupons field explicitly refused rather than silently ignored. It does not add anything about site vs site_domain beyond what the schema already says.

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?

"Price a cart and open a checkout for the owner to pay in their browser" gives a specific verb and resource plus the human-in-the-loop boundary. It explicitly routes to siblings get_checkout and get_download, so an agent can distinguish it from every other tool in the list.

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

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

It states the follow-up sequence (poll get_checkout until status is "paid", then get_download) and when each license kind applies: site = one website with site_domain required, unlimited = every site the owner owns or runs but not client sites, reseller = only where get_app lists a reseller price. It also says what to do on refusal (past N sites, tell the owner to ask for more) and not to guess codes.

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 safe-read profile, yet the description adds genuinely new context: an authentication requirement (owner signed in) and a default-vs-full response behavior (one-line headline per app unless detail is true, to keep the answer short). It does not describe error behavior when the owner is not signed in, but the added auth and truncation context exceeds the annotation baseline.

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

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

The opening anchor ("the same facts as the account dashboard's Overview") is a strong, front-loaded framing, but everything after it is a single run-on enumeration with parentheticals. The content is dense and useful, yet the lack of sentence breaks makes the list harder to scan 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?

With no output schema, the description carries the burden of explaining returns, and it does so thoroughly by naming each returned fact plus the detail-driven truncation behavior. Authentication is covered; only failure modes and how counts relate to the list_* siblings are left unaddressed, which are minor for a read-only overview.

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 parameter has 100% schema coverage, and the description's "detail: true for every note" merely restates the schema's explanation of the same flag. It adds no new syntax, defaults, or edge-case meaning beyond what the schema already documents, 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?

The verb is implicit but the resource is concrete: an account overview aggregating app/license/site counts, license status, update end date, ownership, latest release notes, and next steps. That enumeration lets an agent know this is the summary-style read, distinct from per-entity siblings like get_license or list_sites. However, no sibling is named, so the differentiation must be inferred from the content list 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?

"Needs the owner signed in" is a real prerequisite and the only explicit usage condition. There is no guidance on when to prefer this aggregate overview over list_owned, list_sites, get_license, or check_updates, which overlap on the same facts. Usage must be inferred from the enumerated contents.

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 openWorldHint=false, so safety is covered; the description adds genuine interpretive context by flagging that 'plan' is deprecated and repeats 'cloudflarePlan', that 'cloudflarePlan' is a plan name and not a price, and that 'price_text' is the plain-words price with cents in 'prices'/'price_list'. It adds an agent-facing obligation (surface beta stage and requirements to the owner before purchase) but says nothing about error behavior for unknown app ids.

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?

Content list is front-loaded, followed by usage guidance and then field disambiguations; nearly every clause carries information. The final clauses about price_text/cloudflarePlan/plan are dense and slightly run-on, but they are all disambiguations rather than filler.

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

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

With no output schema, the description reasonably carries the return-shape burden by naming the returned concepts (requirements, price, versions, stage, inclusions) and disambiguating overlapping price/plan fields. It is nearly complete for a two-optional-param read tool; the only real gap is the app/app_id alias handling and failure modes, which the schema partially covers.

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

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

Schema description coverage is 100%, including the note that app and app_id are aliases and one is required, so the baseline is 3. The description adds no parameter-level guidance of its own — it never mentions app_id or how to source the id (only the schema does, via 'from search_catalog').

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 ('One app's requirements... price, versions, stage... what's included') and enumerates the return contents, which cleanly separates it from list-oriented siblings like list_owned or search_catalog. An agent can tell immediately that this is the single-app detail lookup.

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

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

Provides a clear timing cue: 'Tell the owner the requirements, and that the app is in beta when it is, before they buy,' which places it in the pre-purchase flow. It does not name sibling alternatives (e.g., use search_catalog first to get the id, or check_updates for versions) nor state exclusions.

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

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

Annotations only say readOnlyHint=true and openWorldHint=false; the description goes well beyond by disclosing the required permission (checkout:create, same as create_checkout), the visibility restriction ('Only your own checkouts are visible'), refund semantics on held/needs_refund, and the meaning of a pending+cannot_pay combination. No contradiction with the read-only annotation — this is purely a status read.

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?

Information-dense with almost no filler, but it is delivered as one sprawling semicolon-chained sentence that mixes return-value semantics, next-step routing, marketing guidance for pairs_well_with, and permission notes. The status list is front-loaded, yet the run-on form makes it hard to scan and the pairs_well_with instructions are verbose relative to their importance.

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

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

There is no output schema, so the description carries the full burden of explaining return values, and it does: it defines every status string, poll_after_seconds, next_call, and the pairs_well_with payload shape including price and license scope. For a one-parameter read tool, nothing an agent needs to act on the result is missing.

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

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

Schema coverage is 100% and the single checkout_id parameter is already documented in the schema as 'The checkout_id from create_checkout'. The description only echoes the create_checkout provenance and adds no format, length, or edge-case detail. Baseline 3 applies when the schema does the work.

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

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

States a specific verb+resource ('Status of a checkout from create_checkout') and then enumerates every status value with its meaning (pending, paid, confirm, expired, failed, held, needs_refund, cannot_pay). An agent can distinguish this lookup-by-id status tool from siblings like list_orders or get_license 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 routing: 'paid ... call get_download', 'next_call ... is the exact next tool call (get_download once paid; create_checkout or renew_updates with the same order after expired, failed or cannot_pay)'. It also states prohibitions ('never pay again', 'don't send the owner to it', 'never add one or start a checkout for it unless the owner asks'), which is exactly the when-not guidance most tools lack.

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

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

Well beyond the annotations, it discloses side effects (free apps not yet owned are claimed first, same as claim_free_app), what is never done (paid apps are not purchased), refusal behavior with exact fixes, the 10-minute link lifetime, and the $SITE_APPS_KEY vs browser-sign-in secret distinction. This is consistent with readOnlyHint=false and idempotentHint=false, and confirms nothing is destroyed. It does not cover rate limits or concurrency, so not a 5.

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

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

Every sentence carries substantive information with no filler, and the purpose is front-loaded. However, it is a single dense block of roughly 250 words mixing tool behavior, installer guidance, and owner-communication instructions, which makes it harder to scan than a structured definition would 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?

With no output schema, the description fully compensates by describing return contents (short-lived link, sha256, per-app requirements, download.command, download.needs) and the installation procedure. For a 5-parameter tool with complex side effects, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so the schema already defines all five parameters. The description nevertheless adds meaning the schema does not fully convey: the implicit claim-first behavior of `apps`, the fact that Site Health is injected unless removed via `without`, and that `detail: true` surfaces the bundle manifest also present in the zip. The `site`/`site_domain` short-form relationship is only lightly restated.

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

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

Opens with a specific verb+resource ('Prepare the download for one site') and enumerates the artifact contents (core, apps, skills, INSTALL.md, manifest, license, signature). It also distinguishes its behavior from siblings like claim_free_app, create_checkout and renew_updates by naming those flows explicitly.

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

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

Gives explicit when-to-use rules: pass `apps` for requested apps, omit it to get every owned app covering the domain, use `without: ["health"]` to exclude Site Health, and use detail:true for the full manifest. It also states the exclusions — paid apps are never bought here and are refused with a create_checkout pointer — which routes the agent to the right alternative.

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 openWorldHint=false, so the safety profile is covered; the description adds genuinely new behavioral context with "Needs the owner signed in", an auth constraint not present in any structured field. It also discloses the shape of returned data, though it says nothing about behavior when the license is absent or when app_id matches many licenses.

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

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

Three sentences, no filler, with the lookup-key guidance and auth prerequisite placed after the payload summary. The opening sentence is a long comma-separated field list rather than a verb-led statement of purpose, which slightly delays the agent's recognition of what the tool does.

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

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

With no output schema, the description carries the return-value burden and does so thoroughly by enumerating the license facets. The remaining gaps — error behavior for unknown ids and result volume when app_id returns multiple licenses — are small but real for a lookup 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%, so the baseline is 3, but the description adds value beyond the schema: it names get_account as an additional source for license_id (the schema mentions only list_owned) and frames the two parameters as alternatives ("license_id ... or app_id"), clarifying the either/or selection the schema leaves implicit.

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

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

The description enumerates exactly what a license record contains — type, billing, status, update expiry, covered versions, sites, renewal/upgrade availability — which makes the resource unmistakable and implicitly separates it from the list-style sibling list_owned, which it names as an id source. It never states the verb outright ("get/return"), relying on the title to supply that, which keeps it 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?

It gives concrete invocation guidance for the ids ("license_id (from list_owned or get_account)" or "app_id (every license for that app)"), so an agent knows where to get the inputs, and it flags the sign-in prerequisite. However, it never says when to choose this over get_app or list_owned — the comparison 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 establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely new behavior context, namely that the payload is full Markdown and that 'start-here' has special first-time-setup semantics, but it says nothing about size, truncation, or what happens when a slug is missing or stale.

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 return format front-loaded, which is the right ordering. The quoted 'start-here' is slightly awkward phrasing but not wasteful.

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

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

With no output schema, the description correctly spends its words telling the agent what comes back (full Markdown of verified steps) and flags a notable special slug. For a one-parameter read tool this is close to sufficient, with only failure behavior 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 slug property already says it comes from search_catalog, so this is the baseline case. The description contributes one useful semantic detail, that 'start-here' is a meaningful special slug, but gives no format or error expectations for an invalid slug.

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

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

The description names the specific resource and its return form: 'the full Markdown of a playbook,' plus what a playbook contains ('verified steps the agent can follow'). That distinguishes it from content-fetching siblings like get_app or get_download, 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 only implied: the schema ties the slug to search_catalog, so an agent can infer this is the fetch step after discovery, and the second sentence carves out a specific case ('start-here' for owners not yet on Cloudflare). There is no explicit statement of when to prefer this over other read tools or what to do when a slug is unknown.

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 read-only and closed-world profile, and the description adds genuinely new operational facts: an authentication prerequisite ('Needs the owner signed in') and the constraint that receipts/invoices are not available from this tool because Stripe emails them. It stops short of describing result ordering, pagination, or what an empty account returns.

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 returned resource set, then routing and auth constraints — no filler. The first sentence's dense enumeration is slightly heavy but every element maps to a distinct returned entity.

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 parameterless read tool with no output schema, the description carries the return-value burden and does list order fields, plus useful scope exclusions and the sign-in requirement. It is less explicit about the shape of subscription payments, renewal-eligible licenses, and upgrade offers, so an agent still has gaps about the full payload.

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 of 4 applies. The parenthetical field list is return-value information rather than parameter guidance.

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

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

The description enumerates exactly what is retrieved: orders (with fields id, date, what, amount, status), subscription payments, renewable-update licenses, and upgrade offers. The verb is only implicit (the noun phrase 'The account's orders...'), but the resource set is specific enough to distinguish it from siblings like list_owned, list_sites, or get_license.

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

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

It explicitly routes one class of request elsewhere — 'to cancel a subscription or change a card, call billing_portal_link' — and rules out receipts/invoices since Stripe emails those. However, it gives no positive trigger for when to call this versus get_license, check_updates, or renew_updates, which overlap with the 'licenses whose updates can be renewed' content.

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

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

Annotations already declare readOnlyHint and closed-world scope, so the safety profile is covered. The description goes beyond them by naming the auth requirement and, importantly, enumerating what comes back (app, site-vs-all-sites license, provenance free/order/grant, update end date) — valuable since no output schema exists. It stops short of saying how results are ordered or whether they can be truncated.

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 tight sentence with the subject front-loaded and no filler. The field list is dense but slightly cryptic in places — 'license (site or all sites)' reads as shorthand an agent must decode.

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 no-parameter read tool with annotations covering safety, the description supplies the missing pieces: what is listed, what fields appear, and the sign-in requirement. Only minor gaps remain, such as result volume or whether the list is paginated.

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 schema baseline applies. The parenthetical distinctions like 'site or all sites' describe returned data rather than inputs, which is useful but belongs to output transparency, not parameter 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?

The phrase 'The apps this account owns' plus the enumerated payload fields makes it clear this is a listing of the account's owned apps and their license/provenance/expiry state. It is distinguishable from singular siblings like get_app, get_license, and get_download, though it never explicitly contrasts itself with list_sites or list_orders.

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 the precondition 'Needs the owner signed in,' which tells the agent about authentication but not when to reach for this over get_app/get_license. Usage is implied by the scope word 'owns' rather than stated as a selection rule.

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 and openWorldHint=false, and the description adds genuinely new behavioral context: an authentication prerequisite ('Needs the owner signed in'), a data-provenance caveat ('the store can't see what is deployed', 'when the registry last saw it'), and a privacy note about registry visibility. These tell the agent how to interpret freshness and what the versions actually mean. It stops short of ordering, pagination, or size expectations for the returned set.

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 size is reasonable for the amount of return-value detail, and the subject is front-loaded in the first clause. However, the delivery is a single run-on sentence with stacked parentheticals and garbled phrasing ('versions_are says so'), which forces re-reading to separate the installed-vs-deployed caveat from the field list.

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 and no output schema, the description carries the whole burden of explaining results, and it does so thoroughly: per-site app entries, the three version fields, update/renewal flag, client_label, and last-seen timestamp. Missing only secondary operational details such as result ordering, pagination, or behavior for accounts with many 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?

The tool takes zero parameters, so there is no parameter meaning for the description to add and the baseline of 4 applies. The description's field-level detail concerns return values, not inputs.

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

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

Opens with the concrete resource: 'The domains this account has downloaded apps for', and enumerates what comes back per site (apps, installed/available/latest versions, update status, client_label, last-seen). An agent can tell this is a per-site inventory view. It never uses an explicit verb like 'list' and never contrasts itself with the closest sibling, check_updates, which also surfaces update availability.

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 explicit when-to-use guidance and no exclusions. The mention of 'whether an update is available or needs a renewal' gestures at a use case that overlaps check_updates, but the description does not tell the agent which tool to pick. The only gating statement is a prerequisite ('Needs the owner signed in'), not a selection rule.

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?

Going well beyond the annotations, it discloses a hard rate limit (up to 3 moves a year per license), an audit property (logged), a permission requirement (download permission), and the blast radius of the default call (omitting app_id moves every site license for from_domain). These are exactly the operational facts an agent needs before mutating state.

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

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

Front-loads the core rule and packs constraints into short clauses with no filler. A couple of sentences are telegraphic ('A site license follows one website'), but every line carries information and nothing is redundant.

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

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

For a 3-parameter mutation with no output schema, the description covers rate limits, permissions, and scope of effect, which are the main risks. It is slightly thin on what happens to licenses that cannot be moved (e.g., when the yearly cap is hit) or what the response reports.

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

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

Schema coverage is 100% with per-parameter descriptions, so the baseline is 3. The description still adds meaning the schema lacks: the omitted-app_id behavior and the 'same website only' constraint that binds from_domain and to_domain together.

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 ('move its licenses here') tied to a concrete trigger (the site changes domain). It also scopes out license classes that are unaffected ('All-sites and free licenses already cover every domain'), which sharpens the purpose without naming a sibling tool.

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

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

Gives explicit when-to-use ('If the site changes domain'), a when-not/irrelevant case (all-sites and free licenses), and the key selection rule for omitting app_id. It stops short of naming an alternative tool or prerequisite ordering, so it is strong but not exhaustive.

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 (not read-only, not destructive, idempotent), and the description adds genuinely new context: pricing at roughly half the renewal rate, browser-based payment by the owner, and the required checkout:create permission. It also reassures that the installed version keeps working, though it does not describe what the checkout response contains.

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

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

Front-loaded with the core action and eligibility, and most sentences carry distinct facts (scope default, source of ids, pricing, payment flow, permission). The row of short sentences about pricing and browser payment is slightly sprawling but each remains informative.

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 definition covers eligibility, scoping defaults, pricing, payment mechanism, and required permissions — enough for correct invocation. Only the returned checkout artifact (e.g., a URL to hand to the owner) is left implicit.

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

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

Schema coverage is 100%, so baseline is 3, and the description adds real meaning: entitlement_ids omitted means renew all due licenses, and ids originate from list_owned. The coupon rejection is already documented in the schema, so that sentence adds nothing beyond structured data.

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 action (open a checkout) with a precise resource and effect (adds 12 months of updates to paid licenses whose updates end within 90 days or already ended). This clearly separates it from create_checkout and check_updates in the sibling list.

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

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

Gives explicit eligibility criteria (updates ending within 90 days or already ended) and a scoping rule: omit entitlement_ids to renew everything due, with ids sourced from list_owned. It stops short of naming create_checkout as the alternative for non-renewal purchases, so there is a small inference gap.

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 openWorldHint=false, so safety is covered. The description adds real value by explaining result fields and the stage semantics ('beta': works, but things may still break; tell the owner before they buy), plus the deprecation of plan in favor of cloudflarePlan. However, it says nothing about result limits, ordering, or pagination behavior of the search itself.

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 in the first sentence and the rest is dense field-by-field explanation with almost no filler. The long parentheticals (stage, price_text, cloudflarePlan) make it a heavy read, though each carries useful disambiguation such as 'free' meaning the Cloudflare plan, not the price.

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 appropriately explains the returned fields (category, categories, stage, stage_note, price_text, prices, price_list, cloudflarePlan) and the deprecated plan field. It leaves some gaps for a search tool — result ordering, any limits on returned items, and whether results are scoped to the caller's site.

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, and the description genuinely adds meaning: query is framed as 'what the site needs' with examples, empty query is defined as list-all, and category is described as narrowing apps in catalog order. The kind enum's effect is only implied rather than spelled out.

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 — 'Find site apps and free playbooks (how-tos) by what the site needs' — with concrete example queries ('contact form', 'redirects', '404'). It is clearly a discovery/search tool, distinguishable from detail-fetching siblings like get_app and get_playbook.

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 usage rule for the empty query ('Leave query empty to list everything') and explains how category narrows results. It stops short of explicitly naming when to prefer get_app/get_playbook for follow-up detail, so routing to siblings 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.