Shipfound

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

The annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds two genuinely useful traits beyond them: the audit is 'stored' (a snapshot, not a fresh run) and it is 'Free' (no credit cost), which affects invocation decisions.

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

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

A single front-loaded sentence with a colon-delimited content list and a one-word cost note; nothing is wasted, though the trailing 'Free.' is slightly detached from the main clause.

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-only tool with no output schema, the description adequately describes the shape of the returned content (areas, status, observations, fix). It lacks only return format details such as ordering or pagination, which are minor here.

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

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

The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to compensate for, and it correctly presents the call as argument-free.

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

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

The description names a specific resource (the stored access audit) and enumerates its contents — per-area status, observations, and fix. It implies retrieval rather than generation via 'latest stored', but never states the verb and does not differentiate itself from the nearby record_access sibling.

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

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

There is no explicit when-to-use guidance and no alternative named; the agent must infer that this reads whereas record_access writes. 'Free' hints at the cost dimension but is not usage guidance.

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

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

Annotations declare a non-read-only but non-destructive, closed-world write. The description adds the key behavioral fact beyond annotations: nothing changes in Apple Ads until the founder approves, so the tool stages a proposal rather than mutating live campaigns. No contradiction with readOnlyHint=false. It does not describe rate limits or return 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?

Purpose and constraints are front-loaded and the prose is efficient. The trailing 'Growth. Free.' fragments are ambiguous and add little, slightly diminishing tightness.

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

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

For a staging/proposal tool with no output schema, the definition covers what gets proposed, the required per-item fields, the approval gate, and where IDs come from. Reasonably complete, though bid/matchType semantics and the approval-result flow are left to the schema and caller.

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

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

Schema description coverage is 0% at the top level, so the description must compensate. It explains that each item needs its campaign, ad group, and why, which covers several required fields (campaignId, why) and the source of adGroupId, but omits detail on kind, text, bid, and matchType.

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 (propose) and resource (new exact keywords or negatives) plus their sources, and frames the outcome (founder approval in the results app). It is clearly distinguishable from siblings like ads_review and keyword_research.

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 identifies where inputs come from (keyword_research, the App Store keyword field, reviews) and that campaign/ad group values come from ads_review. It gives strong context of when to use it, but states no explicit when-not or alternative to prefer.

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

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

Goes well beyond the annotations: it discloses the approval gate ('nothing changes in Apple Ads before' the founder approves), the vendor-number prerequisite for afterInstall data, the Apple platform limitation that starts cannot be tied to keywords, and the guardrail that blocks bid/budget increases when no starts occurred. Missing only volume/pagination or rate context for a data-heavy 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?

The core action is front-loaded, but the description is one long chain of colon- and semicolon-separated clauses that takes effort to parse, and some of the proposal-type enumeration restates what could be one sentence. It earns most of its length but not its density.

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-output-schema, zero-required-parameter analysis tool, the description covers the data read, the target semantics, the afterInstall path, and the approval workflow. It does not spell out the shape of the returned proposals or how errors (e.g., missing vendor number) surface, which is the remaining gap.

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

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

Schema coverage is 100%, so the schema already documents days, targetCpi, and targetCostPerStart, including the precedence rule. The description reinforces the target/per-start concept but adds no syntax, formatting, or defaults beyond what the schema provides.

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) plus resource (Apple Ads: campaigns, keywords, search terms) and a second verb (propose changes) with concrete proposal types. It is clearly distinguishable from a pure apply tool, though it never names the sibling ads_propose that would complete the routing.

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

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

Usage is implied rather than stated: the days window, the target parameters, and the condition that proposals wait for approval give context, and the afterInstall gate ('when not one started after enough installs no bid goes up') hints at when it applies. It never explicitly contrasts with ads_propose, ads_setup, or platform alternatives, so the agent must infer the choice.

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 mark this as mutating-capable (readOnlyHint=false) but non-destructive; the description supplements this usefully by explaining the two modes: a read that returns step states plus optimisation hints, and a 'record' that writes what you read. It also gives platform-specific sources (ads.x.com, business.facebook.com, ads.reddit.com, ads.google.com) and concrete 'verified' criteria, which is real behavioural context beyond the annotations.

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

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

The whole definition is one massive, comma-spliced paragraph with an embedded numbered list and a field dump. It is front-loaded with purpose but not structured for parsing, and several clauses (cross-referencing URLs and values) could be scoped to the parameters instead of the body. Length is justified by complexity, but presentation is poor.

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 nested, mutation-capable tool with no output schema, the description does well: it states what is returned (each step's state, optimisation options, recommended ladder step, goals with firability, clicksSeen) and what record persists per platform. The main gap is the absence of a return shape or failure/edge handling, but overall an agent has enough to invoke it correctly.

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

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

Schema coverage is only 50% and the record object is deeply nested, so the description carries heavy load: it explains the meaning of account fields per platform (payment method, business portfolio, Page picture), the tracking pixelId format per platform (X pixel id, Meta dataset id, Reddit a2_/t2_, Google AW- conversion ID with label as event), and the 'verified' semantics. This meaningfully compensates for the schema gap, though some field-level precision still lives only in 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 names the resource (ad-platform setup state for a boost) and enumerates the three steps it reports (account, tracking, launch), plus a record mode. However, the purpose is buried inside a dense run-on sentence, and it never cleanly distinguishes itself from near-neighbours like tracking_check, launch_prep, or ads_propose. It is decipherable but not crisp.

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

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

There is no explicit 'use this when / not when' guidance and no siblings are named as alternatives. A reader can infer it is the setup-status tool, but nothing routes the agent between ads_setup, tracking_check, tracking_install, and launch_prep. The record mode is described mechanically but not framed as a when-to-use decision.

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

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

Annotations already declare read-only, closed-world, non-destructive, so the safety profile is covered. The description adds the default lookback window and notes about AI Search and shipped_work dimensions, but says nothing about result volume, the 500-item cap, or whether reports are paginated — meaningful gaps for a 14-report tool.

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

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

One tight paragraph: the capability first, the report list second, then defaults. No preamble or repetition of the schema, and the trailing notes are 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?

With 9 parameters, no output schema, and only partial schema descriptions, the description should clarify filter behavior and per-report parameter applicability. It covers defaults and a couple of domain quirks but leaves an agent guessing about how to shape filters and dates for specific 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 56%, and the description fills one hole by stating the default period, which informs from/to. But it adds nothing about filters, siteId, limit, or which parameters are only valid for certain reports (metric/interval scoping lives in the schema, not the prose). Baseline 3 fits.

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 and resource ("Run any report on the site's traffic") with the full report vocabulary enumerated, so an agent knows exactly what it retrieves. It doesn't explicitly contrast with neighbors like visibility or search_positions, but the traffic-report scope is clear enough to separate them in practice.

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 useful default ("last 28 days") and implies this is the go-to traffic query, but never states when to pick this over siblings (visibility, search_positions, funnel_check) or when-not to use it. Selection is left to inference from the report enum.

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

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

Annotations declare this is a non-read-only, open-world, non-destructive write, and the description usefully adds that it fetches a public listing and enumerates exactly which fields are read (name, subtitle, rating, reviews count, languages, screenshots). It also discloses cost ("Free"). It does not state idempotency or auth/permission requirements, keeping it short of a 5.

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

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

Two sentences, front-loaded with the action, each carrying distinct information (source, fields read, cost). No filler or restated 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?

With no output schema, the description compensates by telling the agent what the listing read returns. For a single-parameter add tool with annotations covering the safety profile, this is nearly complete, though it could clarify what the tool itself returns after adding.

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?

Only one parameter, and the schema already documents it at 100% coverage. The description nonetheless adds the concrete URL shape ("apps.apple.com/.../id123"), giving a usable format example beyond the schema's generic "apps.apple.com link".

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 ("Add the founder's iOS app to this workspace") plus the input source (App Store link) and the data that will be pulled. This is clearly distinguishable from sibling listing/read tools, but it never names an alternative to contrast against, so it stops short of the top mark.

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 "Add the founder's iOS app to this workspace" — an agent can infer this is the first-time add step. However, there is no explicit when-to-use vs siblings (app_metadata, app_audit, app_downloads) and no prerequisites or exclusions stated.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint, so safety is covered. The description adds real behavioral context beyond that: the tool is free, it does not apply fixes ('the fixes are yours to write, as a PR'), and the keyword field is only visible when repo locales are supplied. Missing only auth/permission notes.

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 audit scope before the operational guidance, with no filler sentences. The parenthetical file list is dense but earns its place by disambiguating the nested parameter.

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 audit with no output schema and a complex nested input, the description covers what is checked, what differs between the two modes, and how to source the locales payload. Return format and result shape are the main omissions, but those are acceptable given there is no output schema to be consistent with.

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

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

Schema coverage is only 33% and the nested `locales` object has no field-level descriptions, so the description has to compensate; it does so by mapping the fields to concrete fastlane filenames (name.txt, subtitle.txt, keywords.txt, promotional_text.txt, description.txt). `appId` is left unelaborated, but the locales guidance adds substantial meaning over the raw schema.

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

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

States a specific verb and resource (audit an app's App Store metadata) and enumerates the concrete checks: character limits, wasted keyword characters, cross-field repetition, locale indexing, screenshot captions, AI-answer readiness. This is far more specific than sibling names like app_metadata or check_content, letting an agent route to it directly.

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

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

Clearly explains the two operating modes: passing `locales` from fastlane metadata triggers the full check, omitting it limits the audit to the public listing (with the keyword field unavailable). It does not explicitly name sibling alternatives or exclusions, but the conditional usage 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?

With readOnlyHint=false, the description usefully explains the state side effect: 'the latest read is kept for grow', which is why the tool is not read-only. It also discloses the external dependency and auth requirement (App Store Connect with Admin role) and that the call is free, which annotations alone cannot convey.

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

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

Front-loaded with the ranking rationale and tiers, then the input/fallback rules, then cost/retention. It is dense but each clause carries information; the middle ranking sentence is long but not padded.

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

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

With no output schema, the description does the necessary work by describing what each result contains ('the App Store Connect locale to write and its language') and the ordering logic. The only missing piece is the meaning of `appId`, which is also absent from the schema.

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

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

Schema coverage is 50%: `locales` is documented in the schema, and the description reinforces its meaning by naming its source (fastlane/metadata/<locale>/ folder names) and the fallback semantics. `appId` is explained in neither the schema nor the description, leaving a real gap.

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

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

The description states precisely what is returned: 'The countries the app's listing could open next, best first', including the ranking tiers. The resource (countries for App Store listing expansion) is distinct from siblings like app_metadata or app_keywords, though the differentiation is implicit rather than by naming a sibling.

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

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

It gives clear conditional input guidance (pass `locales` from fastlane folders when App Store Connect is not connected, otherwise the listing counts as storefront-language only) and a prerequisite (Admin role). However, it never says when to use this tool versus the many adjacent planning tools (launch_targets, listing_targets, plan), so routing remains inferential.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, and the description adds real context beyond them: the page is created as a draft, it inherits the live version's media, keywords must already exist in the approved keyword field, and Apple only shows it in search after approval. It still doesn't say what the call returns (page id, draft state) or what happens on duplicate name.

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

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

The core facts are front-loaded, but the opening is a long run-on sentence with parenthetical nesting, and the trailing fragments 'Growth. Free.' add taxonomy noise without operational value.

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

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

For a mutation tool with no output schema and low schema coverage, the description does cover draft semantics, media seeding, keyword constraints and the downstream review step. Gaps remain: the non-existent 'ppid' param confuses the interface, and default behaviors (locale default, what the response contains, what happens to the live page) are 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 only 29% across 7 params, so the description must compensate; it does add meaning for keywords (approved-field restriction), screenshots (new captioned screenshots seeded from live media) and the App Store search effect. But name, appId and locale are left entirely to the sparse schema, and it references a 'ppid' parameter that does not appear in the schema at all, which is a mismatch rather than added clarity.

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 ('Make a custom product page as a draft') plus the scoping intent ('for one audience or search'), so the agent knows exactly what is produced. It does not explicitly name the nearby siblings (app_cpp_list, app_metadata_stage), leaving the differentiation implicit.

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

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

The phrase 'for one audience or search' and the keyword constraint ('only words already in the approved keyword field can be assigned') imply when this is the right tool, and the note that the founder submits for review in App Store Connect sets expectations after the call. However, there is no explicit when-not guidance or named alternative (e.g., app_cpp_list for existing pages, app_metadata_stage for metadata edits).

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely new context beyond structured fields: the call is 'Free' (a cost disclosure no annotation captures) and the return shape is per-page with a ppid. It omits pagination or result-count behavior, keeping it below 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?

One information-dense sentence with no filler, front-loading the resource and then the key usage detail. It is a verbless fragment ('The app's custom product pages...'), which is slightly awkward but costs no clarity or space.

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

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

With no output schema, the description usefully explains that results are per-page with ppids, and annotations cover the safety profile. It still leaves the appId parameter undefined and says nothing about pagination or result limits, so it is adequate but with clear gaps.

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

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

Schema description coverage is 0% for the single appId parameter, and the description never explains it directly — it only weakly implies app scoping via 'The app's'. With one undocumented param and essentially no compensating text, it does not meet the baseline for an adequately documented 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 identifies the resource (the app's custom product pages in App Store Connect) and what each item carries (a ppid), which distinguishes it from the sibling app_cpp_create write tool. The list verb is only implied by the title, not stated in the description itself, so it falls short of the 5 benchmark.

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

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

It gives a concrete downstream use for the ppid values — linking from a shipfound.site page (app_site) or an Apple Ads ad group — which implies when you'd call it. However, it names no alternative tool and states no condition for choosing this over app_cpp_create or other listing tools, leaving the routing to inference.

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

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

Beyond the readOnly/openWorld annotations, it discloses real operational facts: the App Store Connect key needs the Admin role, Apple publishes the first report a day or two after connecting, and the subscription output only appears when a vendor number is saved. That is genuine behavioral context; it stops short of saying anything about pagination or result volume.

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 ~130-word run-on sentence that packs downloads, subscriptions, and product-page metrics into a single breath. The main purpose is front-loaded, but the remainder is dense and hard to parse, and metric definitions like startRate and pageRate are buried mid-stream.

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 does a good job enumerating what comes back (downloads by source/country/campaign, trial and conversion events, visibility/view/Get counts), which offsets the missing return schema. However, the two input parameters and the conditional nature of the subscription payload remain underspecified.

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

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

Schema description coverage is 0% for both parameters. The description only obliquely implies the 'days' window ('for the last days') and says nothing about the 1–35 bound or what 'appId' expects, so it fails to compensate for the empty schema documentation.

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

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

The description names a specific resource (first-time downloads and redownloads) and enumerates the dimensions returned: source, country, campaign, subscription events, and product-page funnel metrics. It is clear what the tool produces, though it never names a sibling (e.g. analytics, app_countries) to differentiate 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?

Usage is only implied: 'With the vendor number saved, also what came after the download' hints at a prerequisite for the subscription section, but there is no explicit when-to-use / when-not-to-use statement and no alternative tool is named despite many siblings covering adjacent analytics data.

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false and openWorldHint=true. The description adds genuinely non-obvious behavior: the result is a DRAFT that the founder must publish, images are not handled here, and the event has hard lifecycle limits (31 days max duration, card visible from up to 14 days before). It omits auth/scope requirements and what is returned, but adds real value beyond the annotations.

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

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

One dense paragraph that front-loads the resource definition and constraints, which is good. However it opens with a bare noun phrase rather than an action, and the trailing tokens 'Growth. Free.' are unexplained noise that doesn't help an agent decide or invoke.

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

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

With 11 parameters, 8 required, no output schema and low schema coverage, the description should carry more weight. It covers the concept, lifecycle constraints and text limits well, but leaves the agent guessing on enum choice (badge, purpose), date formats, and what a successful call returns.

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

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

Schema description coverage is only 36%, so the description must compensate. It partially does: it gives the per-locale text limits (30/50/120) and, more importantly, explains the timing relationship between publishStart (up to 14 days before) and event duration (max 31 days). But it says nothing about the badge and purpose enums, the optional appId, referenceName, or the expected format of eventStart/eventEnd, leaving half the parameters undocumented anywhere.

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 concrete resource ('an in-app event as a draft in App Store Connect') and explains what such an event is (a card in search results and on the product page for something time-bound). Combined with the title 'Draft an in-app event' and the name app_event_create, the create-draft intent is unambiguous, though the description itself never uses a verb and doesn't distinguish it from siblings like app_events or app_experiment_create.

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?

'Its card and page images are added by the founder in App Store Connect, who then submits it' implicitly bounds the tool's scope: it creates the draft only, and image upload plus submission happen elsewhere. That is useful context, but there is no explicit when-to-use statement, no named alternative, and no prerequisites or 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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral facts: ordering ('newest first'), the fields returned, and that the call is free (no credit cost) — all useful and non-duplicative.

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

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

A single dense sentence with zero filler, front-loaded with the resource and immediately followed by the fields and sort order.

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

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

Adequate for a simple one-parameter list tool with annotations covering safety, but with no output schema and no explanation of appId (required? defaults to the current app?), an agent lacks the information to call it correctly in all cases.

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

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

There is one parameter (appId) with 0% schema description coverage, and the description never mentions it or says whether it's optional/derived from workspace context. With low coverage the description is expected to compensate and does not.

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

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

Names a specific resource (in-app events in App Store Connect) plus the fields surfaced (name, badge, state, dates), which lets an agent distinguish it from the write-side sibling app_event_create. The verb is only implied ('events ... newest first'), so it's clear but not maximally 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?

No statement of when to use this versus app_event_create or other app_* readers; the only contextual hint is 'Free'. An agent must infer that this is the read/list path for existing events.

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 a non-destructive mutation (readOnlyHint=false, destructiveHint=false). The description adds that it creates a draft (not a running test), limits Apple's testing to icon/screenshots/previews, and states the founder must start it—valuable behavioral context beyond annotations.

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

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

The description is front-loaded with the action and constraints; four sentences each add relevant details. The final 'Growth. Free.' is a bit terse but likely categorizes the tool. No major waste.

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

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

For a complex mutation with nested objects and no output schema, the description covers draft status, what Apple tests, duration, and who launches it. It leaves some parameter explanation to the schema, but annotations cover the safety profile.

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 40%, so description should compensate. It only partially does: it mentions treatments (up to 3, captioned screenshots) and trafficProportion, but omits name, appId, and locale. The schema already provides descriptions for some fields.

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 ('Set up'), resource ('product page test'), and scope ('as a draft', 'up to 3 treatments'). It distinguishes from sibling 'app_experiment_list' by focusing on creation of an App Store A/B test.

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 context for use (product page test, up to 90 days) and a crucial usage rule ('The founder starts it... never say it is running'). However, it does not explicitly name when to use this over 'experiment_create' or other experiment tools.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true, destructiveHint=false), so the bar is lower. The description does add genuinely useful, non-derivable context: results live in App Store Connect under Product Page Optimization, and the call is free (no credits). It still omits what the call actually returns or any pagination 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?

Three very short fragments, so nothing is bloated, but the structure is telegraphic and not front-loaded with a verb describing the operation. The sentence order puts the resource first and the cost note last, which is acceptable but not ideal.

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

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

There is no output schema, so the description must carry the burden of explaining what is returned. It gestures at results existing in App Store Connect rather than stating that this tool returns the list of tests, leaving it ambiguous whether the tool returns test data or merely points elsewhere. For a listing tool with an undocumented parameter, this is insufficient.

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

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

Schema description coverage is 0% and there is one parameter (appId). The description's phrase 'The app's' loosely implies app scoping but never explains appId, its expected format (numeric ID vs. bundle ID), or whether omitting it returns tests for a default/all apps.

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 identifies the resource domain (the app's product page tests / Product Page Optimization in App Store Connect) but never states the action. It relies on the tool name 'app_experiment_list' to convey that it lists tests, and gives no differentiation from siblings such as app_experiment_create or experiment_results.

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

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

There is no when-to-use guidance and no mention of alternatives like experiment_results or experiment_create. The only usage-adjacent signal is 'Free.', which tells the agent the call has no cost but not when to prefer 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 real context beyond the annotations: it is free, Apple publishes no volumes so a suggested search is used as a proxy ('a suggested search is one people make'), and the latest check per country is retained for the grow flow — which also explains why readOnlyHint is false. It does not disclose rate limits or the shape of the returned rows.

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 checked, then the verdict taxonomy, then the parameter guidance. It is dense and semicolon-heavy, and the closing 'Free; the latest check per country is kept for grow' is cryptic, but essentially 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?

No output schema exists, and the description compensates by defining all seven verdicts and the four signals reported per search. The only gap is that nothing explains what appId defaults to or how results are keyed when the app is not passed.

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?

Goes well past the 75% schema coverage: it constrains the search strings to the country's language, gives the recommended 3-10 count (versus the schema's looser 1-20), and explains that expand adds Apple's longer suggestions 'up to 20 in all' — a total cap the schema does not express.

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 precise verb and resource — checking App Store searches in one country and reporting rank, suggestion status, competitor naming, and top-5 ratings — and enumerates the verdict vocabulary. An agent can tell this apart from keyword_research or search_positions 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?

It says to pass 3 to 10 searches in the country's language sourced 'from the listing, the repo and the reviews' own words', and notes expand is on by default. That is concrete usage context, but it never names an alternative sibling (keyword_research, search_positions) or states when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds real context beyond them: the required App Store Connect key, where it is configured, and the 'Free' cost signal. It does not describe return format or pagination, but for a read-only tool covered by annotations this is a minor gap.

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

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

Front-loaded with the returned fields, then the prerequisite and the fallback alternative. Dense but every clause carries information; the field enumeration is long but useful for recognizing the tool's scope.

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

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

For a one-parameter read-only tool with no output schema, the description compensates well by listing returned fields, the auth requirement, and the alternative when unauthenticated. The only real hole is the unexplained appId parameter.

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

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

There is a single parameter, appId, with 0% schema description coverage, and the description never mentions or explains it. With low coverage the description should compensate, but it only indirectly implies app context via 'the results app' and does not say whether appId is required, optional, or defaults to the current app.

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

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

States a specific verb (read) and resource (every locale's App Store Connect metadata), enumerating the exact fields returned (name, subtitle, keywords, promotional text, description, what's new) and distinguishing the version being prepared from the live one. An agent can tell what this returns 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?

Explicitly names the prerequisite (founder's App Store Connect key connected on the App Store page) and the fallback when it is missing: 'use app_audit with the repo's fastlane metadata.' The selection condition and the named alternative are both present, leaving nothing 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 set readOnlyHint=false, destructiveHint=true and openWorldHint=true, so the safety profile is partly covered; the description adds meaningful scope detail (writes only to the staged version, never the live listing, never submits), a required human-in-the-loop step, and the free/no-cost trait. It does not explain what happens to unspecified fields in the draft or any auth/rate-limit constraints.

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 main action is front-loaded in the first sentence, followed by the negative boundaries and the operating constraints; the long tail of post-submission steps is dense but relevant. Some segments ("Builder and Growth. Free.") are terse context markers rather than core instruction, keeping it just short of maximal efficiency.

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

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

For a two-parameter mutation with no output schema and no annotations on return behavior, the definition covers what is written, what is untouched, the human review step, and the downstream record_action/verify follow-up. The gaps are the unexplained appId parameter and what the tool returns per field/locale.

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

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

Schema description coverage is 0%, so the description must carry the load, and it partially does: it names the changeable fields and their limits (name/subtitle 30, keywords 100, promotional text 170, description/what's new 4000) and notes new locales get added. However those limits already exist as maxLength in the schema, and the appId parameter plus the 1-40 item bounds are never explained.

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

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

The description names a specific verb and resource ("Write listing changes into the version the founder will submit") and enumerates exactly which fields are affected. It also carves out its boundary against the adjacent actions in the flow ("Never touches the live listing, never submits"), so an agent can separate it from app_metadata reads and the eventual submission step.

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

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

It gives clear sequencing context: stage the text, "Show the founder the exact text first," the founder later submits, then record_action and verify. That tells the agent where this call sits in the workflow. It stops short of naming alternatives or exclusions (e.g., when to use this vs listing_skip or app_metadata).

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

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

The description specifies crucial behavioral constraints related to the nomination quality, such as using 'plain' language and avoiding 'no superlatives.' This is vital behavioral context that goes beyond the formal schema structure. Since the annotations provide safety context, the description adds high-value operational context.

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

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

The description is somewhat lengthy and contains conversational filler ('The founder submits it', 'Growth. Free'). While the information is well-organized, it is not maximally concise.

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 that this is a complex creation tool with low schema coverage, the description is highly complete. It successfully frames the 'why' and 'how' of the nomination process, which is necessary for an agent to use the tool effectively.

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 schema description coverage at only 40%, the description helps by defining the semantic goal of the 'description' field—it must explain what is new, for whom, and why it matters. This provides useful semantic guidance but does not detail the purpose of all 10 parameters.

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

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

The description clearly defines the action (draft a featuring nomination) within a specific system (App Store Connect). It distinguishes this from other app-related tools by focusing on the editorial nomination process rather than listing or metadata updates.

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 usage contexts—for a launch, an update, or new content—and gives critical practical advice regarding timing ('Give them weeks of notice'). While it doesn't explicitly compare itself to every single sibling tool, its context is very specific.

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

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

Annotations only declare a mutation with open-world scope; the description far exceeds that by disclosing the exact guardrails (only decreases, 40% floor, no lowering where already below US price at FX), the approval gate (every proposal needs founder Approve and nothing changes beforehand), and the measurement caveat (no price A/B test; before/after reads per country). This is unusually rich behavioral disclosure and consistent with destructiveHint=false.

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

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

The core purpose is front-loaded, but the body is a dense chain of clauses crammed into few sentences, mixing pricing logic, approval workflow, and measurement caveats without separation. The trailing 'Growth. Free.' tagline adds no operational value and should be cut.

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 mutating, open-world tool with no output schema, the description covers behavior and guardrails well and hints that proposals surface on the results app's App Store page for approval. It does not describe what a call returns (a list of proposals? per-country rows?) or what the appId argument means, so an agent cannot fully predict the outcome of an 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?

There is exactly one parameter, appId, with 0% schema description coverage, and the description never mentions it or clarifies whether it is optional (required count is 0). It alludes to 'the app' only obliquely, leaving an agent unsure what to pass or what happens when it is omitted. The description therefore fails to compensate for the schema gap.

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

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

The first sentence states a specific verb and resource: propose a lower subscription price per country, derived from World Bank price levels and snapped to Apple price points. It is clearly distinct from siblings like app_purchases or offer_plan, though it never names an alternative tool explicitly. The trailing 'Growth. Free.' fragment is noise that dilutes an otherwise precise statement.

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

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

It specifies the targeting condition (countries with first-time downloads and opened listings) and hard constraints (decreases only, floor of 40% of current price, skip countries already below US price at FX). However, it never says when to call this versus app_purchases, offer_plan, or boost_plan, nor what to do if no countries qualify. Usage is implied rather than instructed.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true, destructiveHint=false; the description adds useful context beyond them: the data comes from App Store Connect (explaining openWorld), the call is 'Free' (no credit cost), and the read is retained 'for grow', which partly explains the non-read-only hint. It still omits auth/prerequisite state and what happens for apps with no purchases; the read-only framing versus readOnlyHint=false is a mild tension but is mitigated by the 'read is kept' note.

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 resource statement is front-loaded and the three defect categories are concrete, but the prose is run-on and contains opaque fragments ('Free; the read is kept for grow') and an editorial aside about Apple's undocumented ranking that costs length without guiding invocation.

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

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

With no output schema, the description usefully previews the return shape (per-language names/descriptions plus problem flags) and annotations cover the safety profile. The main missing piece for a correct call is how to supply or omit appId and whether results span multiple 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 description coverage is 0% and there is a single appId parameter that the description never mentions. It does not say whether appId is a numeric App Store ID or bundle ID, nor what happens when it is omitted (required count is 0, suggesting a current-app default) — a gap the description was the only place to close.

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 concrete resource (in-app purchases and subscriptions from App Store Connect) and enumerates what comes back: display names/descriptions per language plus flagged problems. The action is implied by the noun phrase rather than stated as a verb, and the sibling app_purchases_stage is never mentioned, so an agent must infer whether this reads or stages purchases.

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

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

There is no explicit when-to-use statement and no exclusion or alternative named, despite a very similar sibling (app_purchases_stage) existing. The 'what to change' clause hints at a diagnostic/audit purpose but never states the condition that should select this tool over app_metadata or app_keywords.

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, the description discloses important behavior: Apple reviews the changes with the next submission and nothing appears before then. It also adds a review/confirmation step by telling the agent to show the founder the exact text first, though it does not mention limits such as the 40-change maximum.

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 front-loads the main action and packs useful constraints and behavior into a compact passage. The fragments 'Builder and Growth. Free.' are terse and slightly cryptic, but they do not obscure the core instruction.

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

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

For a mutation tool with no output schema, the description covers the critical behavioral facts: delayed visibility after Apple review, per-language update rules, and a confirmation step. The main remaining gap is that appId and the changes-array cap are not explained in prose.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It usefully explains character limits, per-language behavior, and the rule that a new language needs both name and description, but it does not explain appId or the 40-item changes limit.

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: write in-app purchase and subscription display names and descriptions per language in App Store Connect. It clearly separates this from a read/list operation, but it does not explicitly name the sibling app_purchases tool for retrieving purchase IDs.

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

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

It gives clear usage context: existing languages are changed, new languages need both name and description, and the founder should see the exact text first. It also explains the review delay, though it does not explicitly compare this tool to alternatives such as app_purchases.

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 open-world, non-destructive, and not read-only; the description adds the details that matter — the once-a-day refresh rate limit, the weekly cadence, that ranks past the first page (~11 apps) come back as null, and that the tool is free. That is real behavioral context beyond structured fields, though it doesn't explain what the refresh actually costs or what the response shape looks like.

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

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

The scope and cadence come first and every sentence carries information, including the null-past-first-page rule. The only soft spot is the internal jargon 'open, gap, weak, and the ones it holds', which assumes knowledge of the keyword-status categories and could cost an agent a beat.

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 does the necessary work: it explains what a record contains (rank per tracked keyword, per country), the time range, the null sentinel, and the refresh semantics. The main omission is `appId` guidance and any hint of the response grouping, which keeps it from 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 coverage is 67%: `country` and `refresh` already have schema descriptions, and the prose only reinforces them (default every storefront, daily cap on refresh). `appId` is undocumented in both the schema and the description, so the prose does not close that residual gap — a baseline 3.

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

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

The description names a specific resource (the app's App Store search rank), the dimension (per tracked keyword, per country), and the time scope (week by week, first read to latest). That is enough for an agent to tell it apart from keyword, visibility, and analytics siblings without opening any schema.

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

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

It establishes clear usage context: normal calls return the weekly series, while `refresh` performs a live country read capped at once a day. It does not name a competing sibling (e.g. visibility or search_positions) or state when not to use it, 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 declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered structurally. The description adds meaningful context beyond that — the data comes from 'Apple's public feed' and is 'Free' — but says nothing about rate limits, freshness cadence, or what happens when an app has few/no reviews.

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 that names the source first and then enumerates return contents. The list-within-a-sentence is dense but every clause carries information; there is no filler or redundancy.

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

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

With no output schema, the description does the valuable work of describing the return payload (star counts, per-version ratings, share of low reviews, the low reviews themselves), and annotations already cover safety. The notable gap is that two of three parameters (appId, country) are never explained anywhere.

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

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

Schema description coverage is only 33%: only 'pages' is documented (50 reviews/page, newest first, default 4). 'appId' and 'country' carry no description in either the schema or the description. The phrase 'the app's' loosely implies appId, but country selection and app-id format are never explained, so the description fails to compensate for the coverage gap.

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

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

The description states a specific resource and its scope — 'the app's latest App Store reviews from Apple's public feed' — and enumerates exactly what data comes back (star counts, rating by version, share of 1/2 star reviews, low reviews). An agent can tell this is a review-retrieval tool. It does not, however, name or distinguish itself from any sibling such as app_downloads or app_audit.

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 implies a downstream use ('for you to group into the to-do list (what to fix, what to answer)'), which hints at when this tool is valuable. But there is no explicit when-to-use statement, no exclusion, and no named alternative among the many siblings, so guidance remains inferred rather than stated.

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

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

With annotations already declaring non-read-only/non-destructive, the description still adds real context: output is a link per image, cost is free, and `proof: "rating"` is conditionally refused under 4.5 stars or 20 ratings — a failure mode invisible in the schema. It doesn't state what artifact is actually created or whether anything is persisted server-side, which is the notable remaining gap given readOnlyHint=false.

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 the dense sentence structure packs size, script coverage, proof, output, and routing into five sentences. The SEO aside ('since 2025 caption text appears to count...') partly duplicates the caption field's own description, which is the only slack.

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-output-schema tool it correctly declares the return ('a link per image'), the permitted image sources are in the schema, and the downstream apply/upload path is named. Only the asset-persistence behavior and the appId/size interaction are left unstated, which is minor but not nothing for a non-read-only 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 only 33%, so the description has to compensate. It does well on three of them: `caption` (benefit wording, search relevance), `sub` (the 'optional second line'), and `proof` (rating line plus its refusal threshold). But `appId`, `bg`/`fg`, and the maxItems=10 constraint on `screenshots` get no explanation anywhere, leaving real gaps.

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: composites a caption (plus optional second line) over each raw screen and renders at the exact App Store Connect size, in any script. It also carves out its position against siblings by naming app_experiment_create/app_cpp_create as uploaders and app_screenshots_apply as the applier, so an agent can distinguish 'render images' from 'ship images' without opening another schema.

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

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

It routes clearly to alternatives: use app_experiment_create or app_cpp_create to upload, app_screenshots_apply to put a set into the next version. It also gives authoring guidance ('write captions as benefits in the words people search'). What's missing is an explicit negative case (e.g. when not to add captions, or what to do if the source screen isn't a raw portrait asset).

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

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

Goes beyond destructiveHint=true by specifying the exact blast radius: it replaces that size's screenshots in that version only, and nothing live changes until the founder submits and Apple releases it. It also surfaces a refusal rule via the proof field (under 4.5 stars / 20 ratings). Minor gap: it does not say whether the prior screenshot set is recoverable or lost on overwrite.

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

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

Front-loaded with the action and its scope; the destructive consequence and the test-first rule follow in priority order. The middle clauses are slightly run-on, but every sentence carries decision-relevant 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 destructive, open-world write with no output schema, the description covers what is mutated, what is deferred to the founder/Apple, and when an untested apply is legitimate. It leaves open what the tool returns (e.g., the applied set or a staged-version id) and how to undo an apply, which keeps 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 coverage is 80%, so the baseline is 3, and the description earns an upgrade by explaining that screenshots are ordered ('in this order') and scoped to a single locale+size per call — semantics the array/param schema does not convey. It still says nothing about why/appId beyond what the enum and field names give.

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 concrete verb and resource ('put a set of captioned screenshots ... into the version the founder will submit') and bounds it to one language and one size in one call. It is clearly separable from app_screenshots (read) and app_experiment_create (test), which are the two obvious siblings an agent would confound it with.

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

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

Explicit routing: 'A change to the screenshots everyone sees is tested first (app_experiment_create): apply a set without a test only for a language that has none of its own.' That names the alternative and the exact condition under which this tool may be used untested, plus the audience (Builder and Growth).

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 openWorldHint=true, and the description earns additional credit by spelling out the actual mechanism: without content it returns the current draft and its issues, with content the payload replaces the draft, drafting is free, and publishing is the founder's own action in the results app. It even warns never to tell the founder the site is live before they publish, which is real behavioral context beyond the annotations.

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

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

The identity and read/write split are front-loaded in the first sentence, and the later sentences each add operational value (sourcing rules, free-vs-publish, the live-claim warning). It is dense and slightly long for a single paragraph, but appropriately sized for a nested content tool with no wasted sentences.

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 complex nested-payload tool with no output schema and zero required parameters, the description covers read behavior and return shape ('returns the current draft and its issues'), write/replace semantics, the sourcing constraints against invented numbers or quotes, and the publish handoff. 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 67%, so the baseline is 3, but the description adds genuine meaning: pages map one-to-one to a search, and each page carries title/description/headline/intro/sections/FAQs plus an App Store or ppid link, which clarifies the intent of ppid and path. It does not explain slug or appId semantics beyond what the schema states, keeping it out of the top band.

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 pair and resource: read or write the app's own small site, with concrete scope (a home page plus up to 11 search-driven pages) and the hosting target. An agent can distinguish this from app_metadata, landing_check, or content_brief without opening another schema, and the sibling keyword_research is explicitly tied in.

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

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

Gives clear context for when this matters ('Most apps have no website, so this is what Google and AI answers can find and cite') and prescribes the workflow: pick each page's search with keyword_research, write from the listing/repo/reviews. It lacks an explicit when-not-to-use or a named alternative for the read-only case, so it stops short of the top band.

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 mark this as a non-read-only, open-world operation. The description adds meaningful behavior beyond that: it stores the key encrypted, validates the key against Bing, checks site verification, and warns against typing the key into a page. It does not detail failure modes, but it substantially explains what the tool does and why.

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

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

The description is front-loaded and information-dense without being excessive. The sentence 'Free.' is abrupt, and the validation sentence is slightly compressed, but overall it earns its space.

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

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

For a one-parameter connection tool with annotations and no output schema, the description covers the essentials: what is stored, that it is encrypted, that it is checked against Bing, and that the site must be verified. It could mention replacement/update behavior, but it is complete enough to call correctly.

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

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

Schema coverage is 100%, so the schema already defines the single apiKey parameter. The description still adds value by saying where the key comes from (Bing Webmaster Tools, Settings, API access) and how it should be handled, going beyond the schema's terse 'The key, as Bing shows it.'

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

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

It states a specific verb ('Store') and resource ('the founder's Bing Webmaster API key') and explains the downstream effect: letting Shipfound read Bing's page data and send pages via Bing's API. This clearly distinguishes setup/connection from the sibling submission tool bing_submit.

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 implies this is a setup step and gives handling guidance ('The founder gives the key; never type it into a page for them'), but it does not explicitly say when to use it versus alternatives like bing_submit or index_status. Usage is inferable but not directly 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 non-readonly, non-destructive, open-world behavior, so the bar is lower. The description still adds genuinely useful context: a daily quota enforced by Bing, the return split between pages sent and those deferred to tomorrow, the founder-approval prerequisite, and that the call is free. It does not describe rate-limit error behavior, but coverage is good.

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

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

Front-loads the action, then prerequisites and return behavior in a compact run of short sentences. Nothing is wasted, though the fragment style ('Free.') and slightly clipped phrasing make it marginally less smooth than ideal.

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

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

For a two-parameter submission tool with no output schema, the description covers prerequisites, quota, approval gate, and the shape of the return value. An agent has enough to call it correctly; only error/retry semantics are unaddressed.

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

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

Schema description coverage is 100%, so both the urls array and the sitemap URL are already documented in the schema. The description reinforces the sitemap-when-given behavior but adds no format or syntax detail beyond the schema, 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 (send pages to Bing through its API) and includes the sitemap variant. Easily distinguished from sibling bing_connect, which is an authentication/setup tool rather than a submission 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 preconditions: only after the founder's yes on the list, and bing_connect must be run first. It also frames the quota boundary that governs whether this tool is appropriate. The only small gap is it does not name an alternative submission path, but the sequence with bing_connect 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 establish read-only, non-destructive, open-world behavior, so the safety profile is covered. The description adds substantial context beyond that: the 30-day window, exclusion of prior boosts, the 48-hour visit/signup prediction model, engagement-vs-usual comparison, and the 'under 500 views = untested, not weak' interpretation. Return shape is only loosely implied (the 'boosted' list), keeping it short of a 5.

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

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

Dense but front-loaded: it leads with what the resource is, then ranking logic, then a caveat, then routing, then cost. Each clause carries information, though the parentheses and semicolons make it slightly tangled to parse.

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: ranked posts, prediction signals, an 'untested' marker, and a separate 'boosted' list. It stops short of describing volume, pagination, or exact fields, but for a single-input read tool it is adequate.

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?

Only one parameter and the schema documents it at 100% coverage ('Their X handle, when the audit did not store one'), so the baseline is 3. The description adds nothing about the handle — reasonable, since the schema already states its emergency/fallback role.

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 founder's original X posts from the last 30 days), the filtering rule (minus previously boosted), and the ranking criteria. It clearly distinguishes itself from boost_plan by routing the latter to a different case, though the verb is implicit rather than stated outright ('returns posts worth boosting').

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

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

Explicit gate: 'Only when the founder asks which post to boost,' with a clear alternative path — 'a post they name goes straight to boost_plan.' It also flags the tool as 'Free,' so an agent knows the cost trade-off. Nothing is left to inference.

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

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

Goes far beyond the annotations: it discloses that nothing is launched or spent, that an equal budget per ad is applied (default $45, cap $300), that firstStep is persisted once per product, that refreshOf drops the replaced boost's messages and returns leftover budget, and that the response includes Ads Manager setup, Review-page checks, and brief.warnings. These are exactly the side-effect, persistence, and refusal behaviors an agent cannot infer from readOnlyHint=false / destructiveHint=false 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?

A single semicolon-chained block of roughly 600 words with no headings, lists, or paragraph breaks, making it hard to scan under time pressure. The most decision-critical line — 'Nothing is launched or spent. Free.' — is buried at the very end instead of front-loaded, and several sentences merely echo the input 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?

Given 18 parameters, nested objects, and no output schema, the description covers all four platforms' asset requirements, default derivation, refusal conditions, persistence rules, and what the response contains. An agent has enough to construct a valid call and predict the outcome without opening any sibling 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 already 89%, yet the description still adds genuine semantics: the $300 budget ceiling and equal split, devices defaulting from the first step (split when a phone can't take it), question overriding budgetUsd, Reddit post-ads forcing Traffic/click optimization, and retargetOf's $20-over-5-days desktop-only default. Some of the text merely restates schema limits (headlines 3–15, 30 chars; descriptions 2–4, 90 chars), which dilutes rather than extends the schema.

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

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

The opening states a specific verb and resource ('Plan a boost') and immediately differentiates behavior per platform — X posts, Google search ads with headlines/descriptions, Meta primary text plus headline, Reddit video vs. text post formats — so an agent knows exactly what artifact is produced. It also names collaborators by name (keyword_research, ads_setup, boost_candidates, experiment_create), which anchors it against 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?

Prerequisites and gating are explicit: 'Refused until ads_setup says the ad account and tracking are done on that platform', visits plans are refused without a firstStep, repeats refused without repeat=true, and too-small optimize steps refused unless force is true. Defaults are traced to their sources (sizing for question, ads_setup recommend for optimize, boost_candidates for ranked). It stops short of explicitly distinguishing this tool from ads_propose/ads_review, so it isn't a full when/when-not/alternative map.

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

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

Annotations already declare this is a non-read-only, non-destructive, closed-world write, and the description adds genuine operating rules on top: never invent a number, omit what could not be read, convert foreign billing at today's rate, and statuses derive from the founder pressing Launch/Publish or stopping. It does not say whether previously recorded numbers are replaced or merged, which is the main behavioral gap for a write tool.

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, but the body is a single run-on chain of semicolons and parentheticals that is dense to parse on first read. Almost every clause carries real information, yet the CSV and currency rules could be split into separate sentences for scanability.

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 5-parameter ingest tool with no output schema and only 40% schema documentation, the description covers both input sources, currency handling, and the no-fabrication rule. What it leaves out is the write semantics against existing records (overwrite vs. append) and any hint of what the call returns.

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

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

Schema coverage is only 40%, and the description compensates thoroughly: it defines `n` as the ad group's/ad set's number in the plan, explains `device` for split boosts, distinguishes link clicks from all clicks (engagements for reach boosts), documents the CSV shape including the 'ad <n>' and 'sf-boost-<id>-<n>' naming conventions and daily-row summing, and clarifies `usdRate` semantics with its default.

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

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

The first clause names a specific verb and resource — record the Ads Manager numbers for a boost — and then enumerates exactly which metrics (spend USD, impressions, link clicks) and for which unit (post/ad, ad group, split-by-device). It is clearly distinguishable from boost_plan (planning) and boost_results (reporting), since this is the ingest step.

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 routing: read from the founder's Chrome for Meta-style boosts, and pass a CSV export for Reddit/Google 'where your browser cannot go', naming the exact export path in each platform's UI. It also states precedence (numbers in posts win over csv). It does not name sibling tools such as boost_results or boost_plan as alternatives, so it falls short of a true 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 mark this as a safe read (readOnlyHint=true, destructiveHint=false), and the description adds extensive behavioral detail beyond them: verdict categories, winner thresholds (90% confidence, 1,500 impressions, 5 signups), costAlarm triggers, taggingNote conditions, path stages, diagnosis outcomes, and retargeting logic. No contradictions with annotations.

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

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

The content is information-dense and most clauses earn their place because there is no output schema. But it is delivered as one enormous run-on sentence with semicolons and colons, making it hard to scan. Front-loading is reasonable, yet structure could be substantially improved with separate sentences or bullets.

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 so thoroughly: metrics, verdicts, alarm conditions, path, diagnosis, device notes, retargeting, and history mode. An agent has enough information to call and interpret 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?

Schema coverage is only 50%, but the description fully compensates. It explains that omitting id returns the latest boost, that history=true returns every prior boost instead, and what history mode returns (links, words, destination, verdict). This gives meaning to both parameters beyond the schema.

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

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

The description clearly conveys that this tool reads a boost's performance: click rate, CPC, CPM, visits, signups, verdicts, path, diagnosis, and retargeting readiness. It distinguishes the single-boost read from the history mode. However, it opens with an awkward noun fragment ('A boost against its stop rule...') rather than a clean verb+resource statement, and does not explicitly name sibling tools like boost_record or boost_plan.

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

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

It gives clear usage context for both modes: 'Without id, the latest boost' and 'With history true, instead every boost launched before.' The purpose of history mode is explained ('so a new boost tests something new'). It stops short of naming alternatives or explicit when-not-to-use conditions against siblings such as boost_record.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true and destructiveHint=false, so the description is not the sole carrier of behavior. It still adds real context the annotations don't: the 4-credit cost, that credits are charged only when a result is returned and nothing is charged on an empty result, that the skill branch is free, and that already-built items are excluded.

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 lead sentence is front-loaded, but the body is a dense semicolon-joined run-on mixing output fields, credit rules and exclusions for two modes. Every clause is informative, yet the structure makes it 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?

For a one-parameter, no-output-schema generation tool, the description is close to complete: it enumerates the fields returned per mode, the billing behavior, and the exclusion rule. The only material gap is the absence of routing guidance against the many sibling tools.

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

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

Schema description coverage is 100% and the single 'kind' enum is already documented with its two values. The description elaborates on what each kind produces, but that is output framing rather than added parameter meaning, so the baseline 3 applies.

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

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

The description states a specific resource (ideas for free tools / agent skills that pull buyers back to the product) and clearly splits it into the two 'kind' modes. It is clear enough to call correctly, but it never distinguishes itself from siblings like keyword_research or content_brief, so an agent still has to infer which generation tool to pick.

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

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

The two enum branches imply when to pick 'tool' vs 'skill' and the credit costs help a decision, but there is no explicit when-to-use or when-not-to-use guidance and no named alternative among the many sibling tools. Usage is only implied.

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

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

The description contributes behavioral facts the annotations do not carry: it costs 2 credits and is 'charged only when it returns' — important billing semantics for an agent deciding whether to call it. The annotations declare readOnlyHint=false and openWorldHint=true, but the description never explains why a 'check' tool is not read-only, leaving that trait opaque.

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

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

Front-loaded with the purpose, then a compact enumerated list of checks, then two short operational sentences about inputs and cost. The middle enumeration is dense and comma-packed but every item earns its place as gate coverage.

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

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

With no output schema, the description usefully enumerates what is checked and discloses cost, giving an agent most of what it needs. It does not describe the return shape (pass/fail vs. list of violations) or whether results differ by content type, which is the main remaining hole for a no-output-schema validator.

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 schema coverage is 0%, so the description must carry the load, and it only clarifies the 'facts' parameter via the content_brief reference. The required enum parameter 'type' (answer_page, comparison, alternatives, glossary_term, article) and 'title'/'markdown' get no explanation, even though gate behavior plausibly varies by content type — a real gap versus the 0% schema coverage.

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

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

States a specific verb and resource: 'Run the gates on a local draft before the PR,' then enumerates exactly which gates (fabrication, unsupported claims, disparagement, duplication, placeholders, banned words, dashes, answer-first opening, headings, length, links). That enumeration lets an agent distinguish this validator from content_brief, which it also names as its data source.

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

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

Gives clear timing context ('on a local draft before the PR') and specifies the data flow from a named sibling ('Pass the facts content_brief returned'), which is actionable routing guidance. It stops short of stating when *not* to use it or what to do after the PR stage, so it is not quite a full when/when-not pair.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true, destructiveHint=false, so the safety profile is partly covered. The description adds genuinely non-structured context: it costs 5 credits and is 'charged only when it returns,' and it explains that facts are read from ranking pages and AI-cited pages. That cost/billing disclosure is exactly the value-add the annotations cannot carry.

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

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

Two sentences, front-loaded with the deliverable, and every clause (sources, headings, PAA, gaps, outline, rules, credit cost) earns its place. The long enumerative first sentence is dense but not padded.

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

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

With no output schema, the description carries the burden of describing returns and does so by enumerating the brief's contents. It also discloses billing behavior. What is missing is guidance on how the output is consumed per content type and any prerequisite/ordering with sibling tools.

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

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

Schema coverage is 100%, so the type enum meanings and topic/keyword semantics are already documented in the schema. The description adds no parameter-level detail (e.g., how topic should be phrased per type) beyond what the schema states. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description names the specific deliverable — a page research brief with facts+source URLs, competitor headings, People Also Ask, gaps, outline, and validation rules. An agent can tell this produces research for a single page. It stops short of naming or contrasting with the closest siblings (keyword_research, build_ideas, grow_answer), so it is clear but not sibling-differentiating.

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?

'You write the page in the repo from this' implies the downstream workflow and the constraint that every number must come from a fact, which is useful context. However it never states when to reach for this vs. keyword_research or build_ideas, nor any exclusion conditions. Usage is implied rather than prescribed.

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

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

The description adds real behavioral context beyond the annotations: the 28-day tracking window, that it is free ('Free; kept for grow'), and the important policy that any change found is shipped as an experiment rather than a direct edit. There is a mild tension with readOnlyHint=false since the description frames this as inspection only, though the 'never as a straight change' clause argues the tool itself does not mutate the site; the mismatch is nominal and not a hard contradiction.

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

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

Everything stated is substantive, but it is delivered as one dense run-on with unexplained shorthand ('the founder's tracking', 'A missing way on ships as') that forces re-reading. The purpose is front-loaded, but the cost/behavioral notes ('Free; kept for grow') are cryptic rather than compact.

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 only sparse annotations, the description carries the burden and largely meets it: it enumerates the reported metrics (link placement, signups vs. page average, visible signup form fields) and the measurement window. What it lacks is any hint about result shape or volume for the top-pages list, but for a zero-argument analysis tool this is close to sufficient.

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 schema has zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly implies no inputs are needed, instead defining the fixed scope (28-day window, pages beyond home).

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 does identify a concrete resource: the top landing pages beyond the home page (articles, answers, comparisons) and what it reports about them (in-page vs header-only links to signup/pricing/checkout/app, signups per landing, signup form fields). But the phrasing is heavily metaphorical ('the founder's tracking', 'the pages that bring visitors, read for a way to sign up'), so an agent must parse it to extract the verb+resource. It also never distinguishes itself from the many adjacent analysis siblings (landing_check, funnel_check, analytics, visibility).

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: audit high-traffic pages for missing conversion paths. The only explicit routing is downstream ('ships as an A/B test (experiment_create), never as a straight change'), which tells the agent what to do with a finding but not when to pick this tool over landing_check or funnel_check. No when-not conditions are given.

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 give the safety profile (destructive=true), while the description discloses the full behavioral chain: it records the kept variant, ships it as the sole page version, removes experiment code in the same PR, writes a record_action entry under module EXPERIMENTS, and costs nothing. That is substantial side-effect context an agent cannot get 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?

Front-loads the core action ('Stop a test') then sequences the consequences in the order they occur. Compact overall, though the 'Free.' fragment and the internal 'record_action ... module EXPERIMENTS' reference are slightly jargony.

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, no-output-schema mutation with documentable params at 0% coverage, the description covers the important side effects and the key 'keep' semantic well. The remaining gap is the meaning of 'note' and 'site', which no structured field explains.

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

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

Schema coverage is 0% across 4 params, so the description carries the burden. It clarifies the 'keep' semantic ('the winner, or the control when nothing won'), which is genuinely useful, but leaves 'key', 'note', and 'site' unexplained. Partial compensation only.

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

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

States a specific action ('Stop a test') plus the concrete follow-on effects: record the kept variant, ship it as the page's only version, remove experiment code. This distinguishes it clearly from experiment_create and experiment_results without needing to open 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?

Usage is implied: call this when a test has concluded and you want to promote a winner/control. There is no explicit 'use this instead of X' or exclusion guidance, and the 'Free' note is a cost hint rather than a selection rule. Adequate but leaves the agent to infer the trigger condition.

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

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

Goes well beyond the annotations: discloses tracking behavior (visit-level assignment, nothing stored for anonymous visitors), that it reads 28 days of page data, that it computes required sample size and duration from mde, that low-traffic pages still start with "not enough yet" status, and what is returned (variant-ship code for Next.js or plain HTML). Those are exactly the side effects and outputs an agent cannot get from readOnlyHint/destructiveHint=false.

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

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

Front-loaded with purpose, then progressively detail. Nearly every sentence carries information, including the trailing "The control is the first variant" and "Free." The tracking-mode sentence is the densest and slows first-read comprehension slightly, keeping it off a 5.

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

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

No output schema exists, and the description covers the return value (the code to ship as a PR) and the success-but-early state ("not enough yet"), which is the critical piece. It leaves unaddressed what happens on a duplicate or conflicting key and whether recurring tests per page are limited — minor for a non-destructive create.

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

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

Schema coverage is 75%, so the baseline is 3; the description earns an extra point by explaining the one parameter the schema leaves bare — mde, its default of 0.2 and its 20% meaning — plus reaffirming that the control is the first variant. Site, key, path, goal and hypothesis are already documented in the schema, so no further compensation is required.

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 — "Size and start an A/B test on one page against one goal" — which is far more precise than the title alone. The "one page" scope implicitly separates it from app_experiment_create, but no sibling is named explicitly, so an agent must infer the boundary.

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

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

Usage is implied through scope (one page, one goal, control first) rather than stated: there is no explicit "use this when..." or pointer to experiment_results / experiment_close for the follow-up or to app_experiment_create for app tests. The "quiet page is never refused" note does pre-empt a real agent concern (insufficient traffic), which is a partial when-not clause.

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

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

Annotations already declare this a read-only, non-destructive, closed-world call, so the safety profile is covered. The description does add genuine context beyond them: the conversion-counting window ('only at or after the visitor's first exposure'), the result ordering ('running first'), the no-cost note ('Free'), and the verdict-interpretation guardrail.

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

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

Dense and largely front-loaded, with the payoff fields listed first and short imperative sentences closing it out. The long field enumeration is justified because no output schema exists, though the opening clause describes return content rather than stating the tool's purpose up front.

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

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

With no output schema, the description carries the full burden of describing returns and does so thoroughly, plus annotations cover the safety profile. The remaining gap is the unexplained 'site' parameter and no note on whether results are live versus cached.

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

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

Schema description coverage is 0% for two parameters. The description partially compensates for 'key' by explaining the unkeyed behavior (all tests in the workspace, running first), which implies key selects one test. But 'site' is never mentioned, leaving half the surface undocumented in both schema and description.

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

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

The description names the resource (an A/B test) and enumerates exactly what is read back: per-variant exposure/conversion counts, rates with 95% intervals, chance to beat control, lift, sample ratio check, and the verdict. It is clearly distinguishable from siblings like experiment_create or experiment_close, though the operative verb is implied rather than stated.

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

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

'Without a key, every test in the workspace, running first' gives a real usage rule for the keyed vs unkeyed case, and 'Never call a winner the verdict does not' constrains interpretation. However, no alternatives are named (experiment_close, app_experiment_list) and there is no explicit when-not-to-use guidance.

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

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

With annotations only declaring readOnlyHint=false, openWorldHint=true and destructiveHint=false, the description carries real additional burden and does: it reads the live site from outside, never creates an account or pays, refuses lines not on the live page, hides shipped fixes until re-read, and is free. It even discloses that the funnel view holds only 28 days of visitors, signups and payments once mapped, which an agent cannot infer from annotations.

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

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

Nearly every clause carries information, but the whole definition is one sprawling pseudo-sentence joined by semicolons, so the core purpose is not cleanly front-loaded. An agent must parse a dense chain of modes and return keys to find the call contract. The content earns its place; the structure does not.

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

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

This is a complex tool with five parameters, nested objects and no output schema, and the description still accounts for the return surface: misses with evidence, fix and id, funnel with mapped steps and leaks, plays, judge, read, and walk. It also names the checks the agent must perform in the browser (mobile-cta, after-signup, upgrade-path), so nothing essential to calling or interpreting it 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 already 100%, so the baseline is 3, but the description adds genuine meaning: it ties each parameter to a mode (record from the read/walk, measure from read.measure.script, outcomes = the founder's own words, skip = ids never shown again) and explains the copy-check quoting rule and the refusal of lines not on the live page. It loses a point because the parameter discussion is threaded through a run-on sentence, making it harder to map back to individual properties.

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 concrete verb and scope: it reads the live home page from outside and follows every button near the top to check whether a visitor can get to signup and payment. The named failure modes (button that only scrolls, broken link, no signup within one click, pricing page with no way to pay) make the tool's job unmistakable. It never names the closest sibling (landing_check) or another alternative, so it stops short of a 5.

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

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

It spells out the operating modes and their triggers in a single chain: call again with record for what the read and the walk found, measure for the phone numbers before and after, outcomes for the founder's list, skip for ids the founder will not fix. It also states lifecycle rules (a shipped fix is hidden until the site is read again; verify re-checks it). It gives no explicit when-not-to-use or sibling routing, so it lands at 4 rather than 5.

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

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

Discloses the two behaviors annotations cannot convey: reusing a name redefines the funnel (overwrite semantics) and `remove: true` deletes it, which matches destructiveHint=true. It also explains the evaluation model (counted from events already stored, returns its last 28 days at once) and that it is free, so an agent knows a save immediately yields results.

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 save/overwrite/delete mechanics are correctly front-loaded, but the body is a dense run-on with heavy parenthetical nesting that is harder to parse than it needs to be. The content earns its place; the packaging does not.

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

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

Covers step types, ordering semantics, defaults, deletion, and the fact that results are computed immediately from stored events — everything needed to invoke it correctly, especially since no output schema exists. Minor omissions (siteId, the 2-8 step bounds, the 90-day window cap) are left to the schema, which documents them.

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?

Goes well beyond the 67% schema coverage by defining each step type operationally — PAGEVIEW paths with wildcards, EVENT names and the name@/path form that t.js sends with no site code, CTA data-sf values, ENGAGED, REVENUE, CHECKOUT as a return from hosted checkout. It also gives the purpose of `any` (alternate ways to satisfy a step) and `evidence` (file:line) plus the defaults for strict and windowDays.

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

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

Opens with a specific verb and resource ("Save a funnel") and immediately narrows the scope to funnels mapped from the site's code, which separates it from funnel_check and goals_save well enough to choose between them. It does not name the siblings directly, so an agent still has to infer that funnel_check is the read-side counterpart.

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 discovery guidance (use analytics page_flow for top pages, where visitors go next, what they click) and a diagnostic rule of thumb ("a step no one reached is usually a wrong pattern"). It never states when not to use it or points at funnel_check for validation, so the routing is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuinely new context: the automatic payment-goal proposal triggered by listing, and the fact that the call is free. It omits auth/workspace scoping and pagination, so it is not a 5.

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

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

Three short, front-loaded sentences with no padding: what it lists first, then the side effect, then the cost. The clipped 'Free.' fragment is terse but carries information, so nothing needs removing.

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 read-only list with one optional parameter and no output schema, the description covers what is returned and the notable side effect. However, it leaves siteId semantics and the behaviour when siteId is omitted entirely unaddressed, which is a real gap for an optional-parameter 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?

SiteId is the single parameter and it is never mentioned in the description, while schema description coverage is 0%. The description therefore does not compensate for the undocumented parameter; nothing tells the agent what siteId is, whether it is required, or what a missing value defaults to.

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 resource and scope precisely: the site's goals (SOFT or HARD) and funnels. An agent can tell what this returns without opening the schema. It does not differentiate itself from the sibling goals_save or funnel_check, so it stops short of a 5.

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

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

There is no statement of when to call this versus alternatives, no prerequisites, and no exclusions. The only adjacent guidance is a side-effect note ('a payment goal is proposed automatically') and a cost note ('Free.'), neither of which tells the agent when this tool is the right choice.

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 the description earns that: it discloses that redefining a HARD goal resets it to SOFT, that every new goal is SOFT by default, and that only the founder can make one HARD. That is substantive context beyond the annotations; return format is the only notable gap.

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

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

Purpose is front-loaded, but the body is one long run-on sentence dense with parenthetical examples, notably the multi-clause CHECKOUT explanation. Information-rich but structure could be tighter and clearer.

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 and only 6 params with low coverage, yet the description thoroughly covers goal types, match semantics, and soft/hard lifecycle. Missing only siteId, valueCents, and any return-value hint — minor given 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 only 17% (only `match` is documented), so the description carries heavy burden — and it does, explaining `match` semantics per type (name@/path, /welcome*, data-sf value, return path for CHECKOUT) and the purpose of `note`. It leaves siteId and valueCents unexplained, keeping it below 5.

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

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

States a specific verb and resource ('Create a goal, or redefine one with the same name') and goes further to enumerate every goal type. An agent can distinguish this from the goals_list sibling instantly.

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

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

Explains the upsert behavior (same name = redefine) and instructs 'Say why in `note`', giving clear usage context. It stops short of explicit when-not-to-use or naming goals_list as the alternative, so not quite a 5.

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

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

Goes well beyond the annotations by disclosing state effects: a no rests the move for 7 days, 30 after a second no; 'seen' keys rest like the first screen's; 'said' text becomes the ranking's direction going forward. This is exactly the kind of downstream consequence an agent needs and annotations cannot convey.

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

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

Front-loads the core action and each subsequent clause carries information about a distinct parameter or consequence. The trailing 'Free.' is wasted marketing text and the sentences are dense, but overall there is little filler.

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

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

No output schema exists, so the description should ideally hint at the response, which it does not. However, it fully covers the input semantics and the resulting state changes for a 5-parameter mutation tool, leaving only return-value shape unaddressed.

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

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

Schema coverage is already 80%, and the description adds genuine meaning on top: what 'from' is used for (learning how often the first three had what they wanted), what 'seen' captures and its resting effect, and how 'said' is consumed verbatim. 'key' and 'answer' remain schema-only, which is acceptable.

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 ('Record yes or no to a move') and anchors the input source by naming siblings ('from today or record_action's next'). The domain term 'move' is slightly jargon-heavy but the surrounding text makes the operation unambiguous.

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

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

Clearly frames the call as the follow-up to showing moves ('today' / 'record_action's next'), and explains the distinction between a yes and a no path. It lacks an explicit 'do not use this if...' exclusion, but the context of use 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 establish this is a safe, read-only, closed-world operation, but the description adds substantial context: the full field composition of each idea (problem, feature, MVP, effort, backer count, posts, key), the meaning of 'kind missing' vs 'unsaid', the exclusion of done/skipped ideas, and that run status, next-free slot, and current price are also reported. This goes well beyond the annotation hints.

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

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

The description is a single dense paragraph that crams return-field definitions, taxonomy explanations, filtering rules, and pricing into one run-on structure with minimal front-loading. The definitions of 'kind missing' and 'unsaid' are buried mid-sentence, and the trailing 'Free.' is disjointed, making it hard to scan.

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

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

With no output schema and no parameters, the description carries the burden of describing returns, and it does enumerate the fields each idea contains plus the ancillary run/price info. It is fairly complete for a zero-arg read tool, though the structure makes it harder to extract than it should be.

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 and the schema is empty, so there is nothing to document. Baseline 4 applies; the description correctly does not fabricate parameter detail.

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 resource: the latest feature-ideas study aggregating what Reddit and X users ask for, grouped into features. An agent can tell this is a retrieval of feature ideas. However, it never explicitly differentiates itself from close siblings like build_ideas, ideas_run, or ideas_skip beyond noting that done/skipped items are excluded.

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 explains what is filtered out (ideas done via meta.idea or ideas_skip) but never states when to call this versus ideas_run, build_ideas, or other siblings. There is no 'use this when' guidance and no prerequisites, leaving the agent to infer the selection context entirely.

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 no destructive behavior, and the description adds substantial context beyond them: the eligibility freshness windows (Reddit <150 days vs 180 archive, X <28 days), one post per thread, a maximum of 5, exclusion of threads already drafted for, and the fact that it is free. It does not discuss permissions, provenance of the 'live' signal, or pagination/refresh behavior, but the added behavioral detail is well above 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?

Front-loads the triggering condition and the outcome, then packs the filtering rules into one dense paragraph. Every clause (eligibility windows, dedup, cap, sourcing) carries information, but the single run-on sentence is somewhat hard to parse.

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

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

With no output schema, the description usefully enumerates what comes back (the idea, the recorded work with live link, the candidate posts). Combined with annotations covering the safety profile and full schema coverage of the one parameter, an agent has enough to decide and call it, though the trigger signal ('verified') is left undefined.

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 there is a single required parameter (key, IDEA:<slug>) whose format is documented in the schema. The description refers to operating on 'the idea' but adds no syntax or constraints beyond what the schema already conveys. Baseline 3 is appropriate 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: it surfaces the people who asked for a feature, once the feature is live, and returns the idea, the recorded work with its live link, and the idea's own posts still worth a reply. It differentiates itself from the sibling ideas_replies_find by explaining what that tool does instead. It stops short of a crisp one-line scope statement (the sentence about what is returned carries the load), so 4 rather than 5.

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

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

Gives a clear precondition for calling it: only once a feature built from an idea is live (PR merged or verified). It also names the related sibling ideas_replies_find and what that one does, which helps route the agent. It does not give explicit exclusions (e.g., when not to call it, or how it relates to ideas_replies_save), so it is clear context without full when/when-not coverage.

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

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

Annotations only say readOnly=false, openWorld=true, destructive=false; the description goes well beyond them by disclosing runtime (~2 minutes, background), cost (8 credits, charged only when drafts are written), a required human confirmation before charging, ranking/source constraints, and the reassuring 'Nothing is posted.' These are exactly the operational facts an agent needs before invoking.

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

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

It is a single dense block with a broken opening clause ('Once a feature built from an idea is live: the run behind Assisted posts...') that reads awkwardly. It is information-rich and mostly front-loaded, but the two most actionable facts for an agent — the 8-credit cost and the wait-for-approval rule — are buried near the end.

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 does state the return value (link to the drafts) and covers side effects, timing, cost, consent, and eligibility exclusions. The only real gap is what happens on failure or when no eligible posts are found, which is minor for a draft-generation 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 50%: 'key' is documented as IDEA:<slug>, but 'platform' has no schema description. The description partially compensates by implying a single platform ('for one platform') and by explaining platform-specific behavior (X a week old at most, Reddit open threads and self-promotion rules), which adds real semantics to the reddit/x enum.

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

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

The description names a concrete verb+resource: find candidate posts and write one reply each about a feature that shipped from an idea, returning draft links. It orients the agent by calling itself 'the run behind Assisted posts (the same as reach_find)', which effectively distinguishes it from the plain ideas_replies sibling. The prose is convoluted, but the scope (this idea, one platform, up to 5 replies) is unmistakable.

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

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

It states a precondition ('Once a feature built from an idea is live'), an explicit exclusion ('never a thread with a draft or a recorded reply already'), and a mandatory consent flow ('tell the founder the price and wait for a yes'). It does not name a direct alternative sibling to route to when the precondition fails, which keeps it 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?

With annotations already covering the safety profile (readOnlyHint=false, destructiveHint=false), the description adds valuable context: one draft per person, duplicate replies are refused, the character-count rule, and crucially that 'Nothing is posted' and the founder posts each one. This clarifies the non-destructive write more than 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?

Single prolonged run-on sentence stacked with parentheticals and nested clauses. It is front-loaded with the verb, but the middle is dense enough that the reader must re-parse the draft/limit/posting rules, hurting scanability.

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 fills that gap by explaining the return value (the Assisted posts link that opens X's reply box, or the Reddit thread). Combined with limits, duplicate refusal, and posting behavior, an agent has enough to invoke it correctly.

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

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

At 50% schema coverage, the description compensates by explaining that each url must be one of ideas_replies' targets (one per thread) and that text is what the person said, bounded by X's 280-character counting with links counted as 23. It adds real constraints beyond the bare schema for the undocumented text field.

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

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

States a specific verb (Save) and resource (replies you wrote yourself to the people who asked for a live feature), and explicitly distinguishes itself from the sibling ideas_replies_find ('finds and writes them'). The core action is clear, though the dense run-on phrasing makes the boundaries of the task slightly harder to extract than a crisp one-liner would.

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

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

Gives an explicit when-to-use condition ('use this only when the founder asks you to write one') and names the alternative tool (ideas_replies_find) that finds and writes replies instead. It stops short of a full when/when-not matrix but routes the agent to the correct sibling.

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

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

With annotations only declaring readOnly/openWorld/destructive flags, the description carries the real operational burden: background execution, a few-minutes runtime, credit cost charged only on return, no charge under 10 readable posts, a weekly free tier, a daily paid cap, and a requirement to disclose price first. That is exactly the kind of side-effect and billing context annotations cannot convey.

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

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

Front-loaded with the purpose and process, and every clause (sources, timing, pricing, quotas, follow-up) carries information. It is one dense run-on chain that would read better split into labeled sentences on cost and quota, so it is efficient but not maximally structured.

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

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

No output schema exists, and the description compensates by telling the agent that results arrive asynchronously via 'ideas'. For a zero-parameter, long-running, credit-consuming job, the description covers runtime, cost, free-tier rules, and how to retrieve results — nothing an agent needs to call it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The description correctly does not invent parameter detail and instead spends its words on 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?

States a concrete verb + resource (run a feature ideas study) and enumerates the exact sources and method: Reddit (last year), X (last three months), busiest threads' comments, this site, grouped asks with evidence. An agent can distinguish this from the sibling 'ideas' (which retrieves results) without opening a schema.

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

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

Explicitly routes the agent to the follow-up tool ('call ideas afterwards') and gives the conditions that gate the call (free quota for Builder/Growth, otherwise 12 credits, one paid study a day). It does not state when to avoid the tool or name competing alternatives beyond the retrieval sibling, so it falls short of full when/when-not guidance.

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

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

Annotations already declare destructiveHint=false and readOnlyHint=false, so safety profile is partly covered. The description adds material behavioral context beyond them: the effect persists across this study and later ones, undo is the escape hatch, and the call is free (implying other actions may cost). It does not discuss permissions or failure modes, but the persistence/reversibility disclosure is genuinely useful.

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

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

Four terse sentences, consequence front-loaded, no filler. 'Free' is the only terse fragment and it earns its place by communicating cost.

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, single-required write tool with no output schema, the description covers consequence, reversibility, and cost, and annotations cover safety. What is missing is minor: no error behavior or note on how to obtain the key (left to the schema).

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

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

Schema coverage is 100%, so key (IDEA:<slug>) and undo are already fully documented in the schema. The description's 'With undo, it comes back' reinforces the undo parameter's effect but adds little beyond the schema's own description. Baseline 3 is appropriate.

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

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

States a specific verb+resource and the concrete consequence: the founder will not build this idea and it is never offered again. An agent can tell it apart from ideas (which supplies the key) and from unrelated siblings, though the description never names a sibling to contrast against.

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

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

Usage is implied by the framing ('the founder will not build this idea'), which tells the agent the condition under which skipping applies. However there is no explicit when-to-use/when-not guidance and no reference to alternatives such as ideas_run or the sibling *_skip tools for 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?

Adds real context beyond annotations: live read ("now"), an authentication prerequisite, a hard cap of ten pages, and cost ("Free"). It does not say what happens when Bing is unconnected or how results are ordered, and the "Reads" framing sits awkwardly with readOnlyHint=false, though nothing claims mutation.

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

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

Front-loaded with the action and returns, then terse fragments for the prerequisite and cost. Dense and mostly waste-free, though the run-on second clause packs the three returned fields into one long sentence.

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

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

With no output schema, the description does the work of explaining return values (indexed status via 2xx crawl, last crawl time, status code) and the prerequisite. Missing only failure behavior when bing_connect hasn't run and whether the cap is configurable.

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

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

Zero parameters, so baseline is 4. The description still usefully explains the implicit data scope (home plus the ten most recently shipped pages), which the empty schema cannot convey.

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 source ("Reads Bing Webmaster Tools") plus the exact scope (home page plus up to ten shipped pages) and the fields returned (indexed?, last crawl, status). It is clearly distinct from siblings bing_connect (auth) and bing_submit (submission).

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 bing_connect first" gives an explicit prerequisite, and the ChatGPT/Bing rationale explains why to call it. It doesn't state exclusions (e.g. when to use visibility or search_positions instead of this Bing view), so not quite 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 give readOnlyHint=false, openWorldHint=true, destructiveHint=false; the description adds crucial cost behavior: 4 credits, charged only on success, nothing charged when data is empty. It also explains the meaning of the 'winnable' flag (difficulty <=30). That goes beyond the annotations, though it does not cover authentication or rate limits.

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 main outputs and keeps the cost model at the end. The single dense sentence is packed but readable; each clause carries information, though the list is long and could be slightly trimmed.

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

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

For a one-param read-heavy tool with no output schema and annotations covering safety, the description provides an unusually complete picture of the return payload and billing behavior. It lacks explicit when-to-use vs siblings and any mention of rate limits or auth, keeping it below 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 coverage is 100%, so the schema already documents the single 'topic' parameter (string, 2-200 chars, 'A keyword or a buyer question'). The description reinforces that it is one topic and outlines the returned fields, adding context about what the topic yields, but the parameter itself is fully covered by the schema.

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

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

States a specific verb+resource (keyword research) and enumerates the exact outputs: search volume, CPC, difficulty, top 10 Google results, People Also Ask, related ideas, and Perplexity citations. This is unusually specific and distinguishes it from siblings like visibility, search_positions or build_ideas.

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 implies when to use it (for one topic, to find winnable keywords) and gives a selection heuristic ('Pick a winnable idea with real volume over a hard one with more'), but it does not explicitly compare to sibling tools such as build_ideas, visibility, or search_positions. Usage guidance is present but not framed as when-to-use vs alternatives.

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

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

The description adds information the annotations do not carry — cost ('Free') and side-effect profile ('reads nothing') — on top of readOnlyHint=false, openWorldHint=true, destructiveHint=false. There is mild tension with readOnlyHint=false, since 'reads nothing' implies a no-op rather than a write, but the description does not affirmatively claim read behavior, so this is not a contradiction.

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

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

Three terse clauses, front-loaded with 'Retired.' so the deprecation is the first thing read, followed by the redirect and the cost note. No sentence is wasted.

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

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

For a zero-complexity retired tool with no output schema, the description covers everything an agent needs: that it is unavailable, what to call instead, and that calling it costs nothing. Nothing actionable 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 0% and the description offers no meaning for 'url' or 'skip'. Normally this would be a hard gap, but the parameters are moot for a retired tool; the deficit is mitigated by the fact that no agent should invoke it with any arguments.

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 plainly that the tool is retired and names the replacement path (funnel_check + routines/convert.md). An agent can immediately tell this tool should not be selected, which is the only purpose clarity that matters for a deprecated entry. It stops short of a 5 because it never says what the tool originally did, so the two schema parameters remain semantically orphaned.

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

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

It gives an explicit when-not (do not use this) and an explicit alternative (call funnel_check and follow routines/convert.md / /shipfound:convert). Nothing is left to inference about routing.

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

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

Annotations establish readOnlyHint=false, openWorldHint=true, destructiveHint=false, and the description usefully adds that state is kept server-side, the service is 'Free', and 'Nothing is posted' — real behavioral context beyond the structured hints. It omits auth/permission requirements, but the added traits are substantive.

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 body is one long run-on built from parameter fragments rather than a front-loaded statement of purpose, so the reader parses schema fields inside the prose. The information density is high, but the structure is poor for quick selection.

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?

All six parameters are addressed and the return payload is summarized ('gates, run-up with today's step, threads'), which suffices given no output schema. However, the vague operation verb and absent usage guidance leave the agent under-informed for a 6-parameter, open-world write 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 already 100%, so baseline is 3; the description goes further by explaining why each value matters (hnUser drives daily karma reads and a Show HN offer, topics top out at 6, threads excludes already-shown/commented ones, the 'closed' enum means 'You can't create posts yet'). That is genuine added meaning over the schema.

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

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

The opening 'Everything before a launch, stored server-side' plus the closing 'Returns the gates, the run-up with today's step, and the threads' conveys a state-persistence-plus-computation tool, but the operative verb is ambiguous (save, fetch, or compute?) and the description never distinguishes it from siblings like launch_targets, plan, or today.

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

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

There is no explicit when-to-use statement and no named alternative. 'Everything before a launch' only implies the lifecycle stage; nothing tells the agent when to prefer this over launch_targets or today, nor any prerequisite ordering.

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, open-world, non-destructive profile, and the description adds real behavior: gates marks boards closed to the founder's account with closed: true and an explicit 'never fill it' instruction, hnUser returns a likely-open signal with a launch_prep fallback, and readiness.blockers/freeTool describe upstream prerequisites.

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 output is front-loaded and every clause carries information, but it is one sprawling run-on sentence dense with enumerated fields (gates, open, productHunt, extras, readiness) that is hard to parse on first read. Tighter structure would improve it without losing content.

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

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

With no output schema, the description carries the full burden and does so: it enumerates the returned fields, their meaning, the closed-step marker, and the readiness prerequisites. An agent has what it needs to interpret the response without a 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%, so baseline is 3, but the description goes further: it explains that hnUser yields a judgment about whether Show HN is open to that account and is read from launch_prep when omitted, and that `all` is only for founder-requested boards.

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 resource and scope: the launch boards that fit this product, minus already-recorded steps. It also implicitly separates itself from launch_prep by explaining that a username stored there is read without needing hnUser. There is no crisp single verb, but an agent can tell what it returns.

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 guidance for the `all` parameter (only when the founder asks for a board by name) and when notOffered applies, but never states when to call this versus launch_prep, listing_targets, or today. Usage is implied by the return contents 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 declare the safety profile (write operation, non-destructive, closed-world), and the description adds durable-state context ('for good', 'from now on') plus cost ('Free'). It omits whether the skip is reversible or what gets returned, but it goes beyond the annotations meaningfully.

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

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

Front-loaded with the outcome and the exclusion list, then the accepted parameter forms, then the alternative. Efficient, though the parenthetical '(wrong fit, paid, rejected them)' and slightly fragmented phrasing make it denser 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 single-parameter, fully-documented mutation tool with no output schema, the description covers what it does, when to use it, when to use the sibling, the persistence of the effect, and the absence of cost. Nothing an agent needs to invoke it is missing.

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

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

Schema coverage is 100%, and the schema already documents 'url, host or key' with examples. The description's 'Takes the target's url, host or key' restates that without adding format or syntax detail, so the baseline 3 is appropriate.

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

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

States a specific action (permanently skipping a target site for listings) with a concrete scope effect: it will be left out of listing_targets and today from now on. It explicitly distinguishes itself from the sibling record_action, so an agent can route correctly without reading either schema.

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

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

Gives explicit when-to-use conditions (wrong fit, paid, rejected them) and names the alternative plus its triggering condition: for a site already listed on, use record_action so it is checked. Both the positive and negative cases are covered.

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

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

Annotations already declare destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the 4-credit cost, that it is charged only when it returns content, and the filtering logic that excludes already-recorded targets. This is meaningful beyond the structured hints.

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

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

Purpose and ranking criteria are front-loaded and every clause carries information (filters, ranking, cost, mode switch). It is dense and somewhat run-on across its two mode sentences, but there is little filler to cut.

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 describing the return, and it does: each target comes with where to submit, and the marketplaces mode describes its own result shape. Minor gaps remain around pagination/count interaction with results, but overall it is sufficient to call 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: the marketplaces flag changes the entire result set (MCP registries, plugin lists, extension stores, awesome lists rather than directories), and it clarifies that include="launch" adds nothing while "review" pulls in G2/Capterra profiles.

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

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

States a specific resource (next directories to list the product on) with concrete inclusion criteria (free to list, open to this product, not already recorded, ranked by AI citation frequency). It explicitly separates itself from launch boards by naming launch_targets and distinguishes its two modes (directories vs marketplaces). An agent can tell exactly what this returns without opening the schema.

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

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

Gives explicit routing: review profiles only appear when requested via include, launch boards belong to launch_targets, and marketplaces=true switches to registries/plugin lists/extension stores/GitHub awesome lists. It also states the credit cost and that it is charged only on a successful return, so the agent knows the price of calling it.

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