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

Annotations only declare readOnlyHint and openWorldHint. The description adds material behavior: the call is free (cost implication), that it is the sole genuine API-key validation endpoint, and that other endpoints can falsely appear healthy. This is high-value context beyond the structured fields.

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

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

Three sentences, each front-loaded with a distinct claim: purpose, cost/validation trait, and the diagnostic action. No filler and no repetition of the title or schema.

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

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

For a zero-required-param health-check tool with no output schema, the description covers purpose, cost, and when to call. It does not describe the shape of the quota payload, but that is a minor gap given the tool's simple diagnostic role.

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

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

Schema description coverage is 100%, so both parameters (format enum, dry_run) are already fully documented in the schema. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific resource (monthly request quota for user and organisation) and specifies it is free of charge and the only endpoint that genuinely validates the API key. This clearly distinguishes it from the many data-retrieval siblings that share the sensortower_ prefix.

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

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

Gives an explicit trigger: 'Call this first when anything returns 401.' It also explains why an alternative is misleading ('/v1/{os}/apps returns 200 with full metadata even for a garbage token'), which is exactly the when-to-use vs when-not-to-use guidance an agent needs.

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

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

Annotations declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe external read. The description adds the estimation nature ("estimates") and scope (date range, multiple apps), but lacks details on rate limits, data freshness, or what the output contains. With annotations covering safety, a 3 is appropriate.

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 single sentence is concise and front-loaded with the core purpose. It could be slightly more informative without being verbose, but it wastes no words.

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 10 parameters, two annotations, and no output schema, the description is too sparse. It omits important context such as available time_period granularity (day/week/month), country filtering, and output format considerations, which are crucial for correct invocation.

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

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

Schema coverage is 90%, with rich parameter descriptions including enums, defaults, and usage hints (e.g., batching, dry_run, format). The description adds nothing beyond the schema, so baseline 3 is correct 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 clearly states a specific resource (active-user estimates) and scope (one or more apps over a date range). It does not explicitly differentiate from siblings like sensortower_app_estimates or sensortower_app_retention, but the resource is distinct enough that an agent can identify its purpose.

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 when-to-use guidance, prerequisites, or alternative tools are mentioned. The description does not explain when to choose this tool over other app-level metric tools such as sensortower_app_estimates or sensortower_app_retention.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuine non-annotation context: the licensing gate that determines whether this endpoint is callable versus its Audience Insights counterpart, which is a real access constraint an agent should know 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?

Two sentences, zero filler, with the core capability front-loaded before the licensing caveat. Tight and well-ordered; it could arguably compress the licensing note but nothing 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 an 11-parameter read tool with no output schema, the description covers purpose, output content (age/gender split plus baseline), and the licensing constraint. Remaining details (dates, granularity, output encoding) are handled adequately by the rich schema, so nothing critical 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 82%, so the schema already documents nearly all 11 parameters, including format, fields, batching, and dry_run. The description mentions the category baseline, which loosely maps to include_baseline, but adds no syntax or format detail beyond the schema — 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?

The description states a specific resource and metric — the age and gender split of an app's users, plus a category baseline — which is far more than a restatement of the name. It also differentiates itself from the sibling sensortower_audience_demographics by licensing tier, though it references the alternative by concept ('Audience Insights equivalent') rather than by tool name.

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 when to pick this tool (App Analysis license holders, generally licensed) versus the Audience Insights variant (separate subscription), which is useful routing context. However, it never states an explicit 'use X when / use Y when' rule or names the sibling tool, so the agent must infer the selection logic.

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

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

Annotations cover the safety profile (readOnlyHint, openWorldHint), but the description adds substantive behavior the annotations cannot: the three per-OS key sets are collapsed to a common shape, revenue is converted from cents to USD, and a request's cost is independent of the date span. That cost/pricing disclosure is genuinely useful context beyond the structured fields, though permissions or rate limits are not addressed.

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

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

Three sentences, zero padding: purpose first, then the normalization/unit contract, then the cost-driven batching rule. Each sentence carries distinct, decision-relevant information and nothing is repeated.

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

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

For an 11-parameter, read-only, open-world tool with no output schema, the description supplies the key missing context: what the returned rows look like after normalization and how units are expressed. Pagination/truncation behavior (the limit param) is only covered by the schema, keeping it just short of complete.

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

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

Schema description coverage is 100%, so the schema already documents all 11 parameters, including the raw flag's effect, the os id formats, and the fields allowlist. The description restates the normalization/units behavior that the raw parameter toggles but adds little parameter-level detail beyond it; 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?

Names a specific resource and scope: 'Download and revenue estimates per app, country and period', and even enumerates the normalized output columns (app_id/country/date/downloads/revenue_usd). An agent knows exactly what data this returns, but the description never names or contrasts a sibling (e.g. app_active_users or app_rank), 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 gives strong operational guidance about batching ('Widen the date range rather than looping: one request covering three months costs exactly what one covering a day costs'), which tells the agent how to call it efficiently. However, there is no explicit when-to-use-this-vs-alternatives statement or prerequisite guidance; selection among the many sensortower_app_* siblings is left to inference.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds the meaningful platform limitation (iOS-only, no Android endpoint), but says nothing about auth, rate limits, or result shape beyond the two mentioned fields.

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

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

Two short sentences, front-loaded with the purpose and followed by the key constraint. Nothing is wasted and no sentence is redundant.

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

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

For a read-only query tool with fully documented params and no output schema, the description covers what is returned (price and duration) and the platform constraint. It could note pagination or result ordering, but nothing critical is missing.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the schema (including batching, fields, format, dry_run semantics). The description adds no parameter-level detail, 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: returns the top IAP SKUs for an app, and adds the returned fields (price, duration). The 'iOS only' constraint helps scope it, though it never explicitly names a sibling tool, so the differentiation is via platform rather than 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?

The iOS-only note gives an implicit when-not (no Android path exists), but there is no explicit when-to-use guidance and no alternative tool is named for related data. Usage is inferable 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 only cover readOnlyHint and openWorldHint, so the description carries the interesting behavioral burden and does so exceptionally: it discloses that the endpoint does NOT validate the API key (garbage token still returns 200) and that an unknown id returns an empty list rather than an error. These silent-failure warnings are exactly the kind of non-obvious behavior an agent needs.

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

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

Three tight sentences, front-loaded with the high-value detail (the unified_app_id) and then the two traps. Every clause earns its place with no filler.

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

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

For an 8-parameter metadata tool with no output schema, the description covers the returned fields, batching behavior, and the critical edge cases (silent auth and missing-id failures), while annotations and the 100%-covered schema handle the rest. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents os/id mixing traps, fields, format, and dry_run. The description adds only the batching limit (100 ids), which the schema's app_ids text also states, so it contributes little beyond structured data.

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

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

The description enumerates exactly what the tool returns (name, publisher, categories, rating, version, unified_app_id), making it clearly the app-metadata lookup. The verb is implicit (a field list rather than 'Fetch metadata for...'), but the resource and scope are unambiguous and it differentiates itself from sibling endpoints by being the source of the unified_app_id.

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 signals a cross-tool dependency by noting the unified_app_id is 'critically' required by every unified endpoint (overlap, audience insights), which hints at when to call this first. However, it never states when to prefer this over siblings like app_estimates or app_rank, and gives no explicit 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 and openWorldHint, so safety is covered. The description adds real behavioral context beyond them: a store id yields an empty 200 that still costs a request, and name resolution costs one extra request per 100 results. These cost/failure semantics are valuable and non-obvious.

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

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

Three tight sentences: purpose first, then the critical id constraint, then the name-resolution cost note. No filler and every sentence carries actionable information.

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

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

For a read-only tool with no output schema, the description covers the input gotcha (unified id), a failure mode, and the cost of name resolution. Pagination and return-shape details are not addressed, which keeps it just under fully complete.

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

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

Schema coverage is 80%, near the high baseline of 3. The description goes further than the schema on two params: it specifies app_id must be a 24-hex unified id (not a store id) and explains that resolve_names triggers additional per-100-results requests, meaning the description adds value the schema does not carry.

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: 'Which other apps this app's users also use.' An agent immediately understands this is cross-app audience overlap. It does not explicitly differentiate from the nearby sibling sensortower_audience_affinity, so it stops short of a 5.

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

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

Gives a concrete prerequisite (get the unified id from sensortower_app_metadata) and a hard usage rule (24-hex unified_app_id ONLY). It does not name a when-not condition or an explicit alternative for overlap-style questions, but the routing to the metadata tool is a clear usage cue.

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, openWorldHint), so the bar is lower. The description earns credit by disclosing a concrete failure behavior — an unknown app id returns 422 'App not found.' here, unlike sensortower_app_metadata — which an agent cannot derive from the schema or annotations. It omits request-cost/pagination context, but the mode requirements and error semantics add real value.

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

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

Three tight sentences, each carrying distinct information: mode=current behavior, mode=history requirements plus a pointer for valid values, and the 422-versus-sibling distinction. The mode branches are front-loaded and there is no redundant restatement of the title or schema fields.

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

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

For a 12-parameter, no-output-schema tool, the description covers the mode logic, the history prerequisites, and an error edge case. Remaining fields (os, limit, fields, format, dates, countries) are documented in the schema, so their absence from the description is acceptable. A brief note on what a rank row contains would fully close the 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 75%, so the schema already documents most fields. The description nonetheless adds conditional semantics that the schema does not express: category and chart_type_ids are required only for mode=history, and mode=current operates on a single app id. That conditional relationship is the key semantic an agent needs and it is stated explicitly.

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

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

The description states a specific verb+resource (returns category rank for an app) and cleanly splits it into two named modes with a precise definition of each ('every category rank an app holds right now' vs 'the daily rank series for a specific category and chart type'). This is distinguishable from siblings like sensortower_top_charts, which aggregate across apps rather than reporting a given app's rank.

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 mode-selection guidance: mode=current for one app id, mode=history requires category + chart_type_ids and directs the agent to sensortower_reference for valid values. It also flags a behavioral difference against sensortower_app_metadata. It stops short of stating when NOT to use this tool (e.g. preferring top_charts for aggregate rankings), so it is clear guidance without explicit 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=true and openWorldHint=true, so safety is covered. The description adds the endpoint path and the bundle-naming gotcha, but says nothing about request charging, pagination, or the shape/width of results (which the schema hints at only via the fields and format params).

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

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

Two sentences, zero padding, with the core capability front-loaded and the constraint warning immediately after. Every clause carries information the agent needs.

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

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

For an 11-parameter tool with no output schema, the description covers the highest-risk pitfall (bundle naming) but omits the semantics of the return data and the interaction between breakdown, regions and format. Adequate to invoke correctly, not complete.

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

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

Schema coverage is 73%, so most parameters are self-documented, and the description adds genuine value on 'bundle' by warning that the bare value 'retention' is rejected. It does not clarify the other ten parameters (regions, breakdown, id_type interplay), so it stays at the baseline for a mostly-documented 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?

It names the specific resource (cohort retention curves) and the three bucketing options, plus the underlying endpoint, so an agent can tell it apart from sibling tools like app_active_users or app_estimates. It lacks an explicit verb and does not name a sibling it is meant to replace, so it falls just short of a 5.

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

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

The description supplies one actionable usage constraint -- that 'retention' alone is invalid and one of the three retention_* bundles must be used -- which prevents a common invocation error. However, it gives no guidance on when to prefer daily vs weekly vs monthly buckets, nor any when-to-use versus the other retention-adjacent siblings.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description goes beyond them by disclosing real behavioral traits: the raw API returns a dict keyed by timestamp and pair arrays, and how each is flattened, ordered (newest first), and filtered (nulls dropped). It does not mention auth, rate limits, or cost.

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 tightly packed sentences front-load the primary mode and each earns its place by explaining a distinct output transformation. Dense but not wasteful, though the parenthetical detail makes it slightly 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 a 10-parameter tool, two modes, and no output schema, the description does the important work of documenting both return shapes. Missing pagination and cost/prerequisite notes, but it is complete enough for correct invocation.

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

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

Schema coverage is 80%, so the baseline is 3, but the description adds genuine meaning for the undocumented 'mode' parameter by defining both enum values and their resulting output shapes. It does not clarify 'full', 'limit', or 'fields' beyond the schema, keeping it short of a 5.

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

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

States a specific verb and resource for each mode: 'lists app version releases' and 'lists which store-listing fields changed on which date.' The two modes are cleanly distinguished from each other, though it does not explicitly contrast itself with siblings like sensortower_app_metadata or sensortower_featured_history.

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?

Explaining the two modes implicitly tells the agent which to pick, but there is no explicit when-to-use/when-not guidance, no mention of alternatives, and no note on prerequisites such as valid app_id or permission needs. Usage is implied rather than stated.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description adds substantial behavioral context beyond them, specifically that most metrics are licensed separately, that a 401 means missing entitlement rather than a bad key (do not retry), and that validation runs before authorization so a 422 is silent on entitlement. This directly shapes how an agent should react to errors.

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

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

Three sentences, front-loaded with the purpose before the licensing caveats, and every sentence carries operational value. The error-code detail is dense but justified for a tool where entitlement failures are common.

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 13-parameter tool with no output schema, the description covers purpose, the dimension-to-metric mapping, and the critical licensing/error behavior. It omits anything about return shape or pagination, but with no output schema and rich parameter documentation that gap is minor.

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 92%, so the schema already documents parameters, making a 3 the baseline. The description adds one conceptual relationship — dimension determines the valid metric/breakdown pair — but does not add format or syntax detail for the 13 parameters 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?

The description states a specific measure and resource ('Affinity of one audience segment for personas, social ad channels, ad categories, advertisers, app categories or other apps'), which is far from a tautology and enumerates the affinity dimensions clearly. It does not name or contrast with the closest sibling (sensortower_audience_demographics), so an agent must infer the boundary itself.

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?

'Pick the dimension and this maps it to a valid metric/breakdown pair' gives some usage context, and the licensing guidance tells the agent what to do after a 401 ('pick another dimension'). However, there is no explicit when-to-use-this-vs-alternatives guidance and no statement of prerequisites before calling.

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

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

Annotations only declare readOnlyHint and openWorldHint, and the description adds genuinely non-obvious behavior: unfiltered shares sum to 1.0, filtered rows are subset WITHOUT renormalising and therefore will not sum to 1, and response age values are bucket starts (18=18-24 ... 55=55+). This is exactly the kind of return-value semantics an agent cannot infer from structured fields.

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

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

Four dense sentences, front-loaded with the identity of the grid before the semantic caveats; every clause carries information. The metric=/breakdown= parenthetical is the one piece that borders on implementation detail an agent may not need.

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

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

For an 11-parameter, no-output-schema tool, the description covers the critical output semantics (sum-to-1, no renormalisation, bucket starts) and the segment grid. It omits row-limit/pagination behavior and when the optional country/format choices matter, but the structured schema handles most of the remaining surface.

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

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

Schema coverage is already 91%, so baseline is 3, but the description adds meaning the schema lacks: the age bucket mapping (25 means 25-34, etc.) and the fact that applying age/gender filters changes summation behavior. It does not explain limit, fields, format, or country, which the schema already covers.

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: it returns the age/gender grid for an audience segment and even names the underlying metric and breakdown. An agent can tell this apart from sensortower_audience_affinity or sensortower_app_demographics conceptually, but no sibling is named explicitly, 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?

Usage is implied rather than stated: you use it to get shares for an audience segment, and the renormalisation note tells you what happens when the age/gender filters are applied. There is no explicit when-to-use/when-not guidance and no named alternative (e.g. versus the affinity or app_demographics 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 read-only/open-world safety, and the description adds genuinely useful behavior: the nonexistent Android route returning an HTML 404, the ~1 MB per category-week payload size, and the date-range implication for cost. It does not disclose ordering guarantees beyond 'newest first' for scope=today or 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 dense sentences, each carrying distinct information (mode semantics, platform limitation, payload size). Front-loaded on the scope distinction, though the opening reads as an enumeration of modes rather than a single crisp purpose statement.

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 10-parameter, no-output-schema tool, the description covers the highest-risk unknowns: platform support, mode semantics, and payload/date-range cost. The remaining parameters (limit, fields, format, dry_run) are self-documented in the schema, so nothing critical 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?

With 70% schema coverage the baseline is 3, and the description earns an extra point by explaining what scope=today vs scope=category actually return and the ordering, which is the key semantics behind the enum. It adds little on limit/fields/format, but those are already documented in the schema.

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

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

The description states a specific resource ('Apple Today tab stories', 'apps featured in one category's sections') and separates the two modes the tool serves. It does not differentiate from the sibling sensortower_featured_history, which is the most likely confusion point, 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 gives a real usage constraint ('keep the date range short') and a hard limitation (iOS only, Android path 404s), which is more than pure implication. However it never says when to pick this over featured_history or how it relates to the top_charts siblings, leaving alternative selection 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 only cover readOnlyHint/openWorldHint, and the description adds genuinely non-obvious behavior: *_series arrays are undated with index 0 as start_date and one element per day, set series to rezip dates, and invalid filters return 200 with empty arrays instead of 422. The last point is exactly the kind of silent-failure quirk an agent cannot get from structured fields.

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

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

Three sentences, no filler, and the highest-value fact (the undated *_series arrays and the series=true fix) is embedded inline with the mode description rather than buried. Every clause carries a distinct operational fact.

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

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

With no output schema, the description does explain return shape per mode (position + download attribution for creatives; aggregated occurrences/downloads for impacts) and flags the empty-array ambiguity. For a 14-parameter tool it leaves pagination and the behavior of undocumented filters like types/countries unaddressed, so it is strong but not exhaustive.

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 57%, so the schema documents some parameters (os, limit, fields, format, dry_run, series, nonzero, breakdown) while leaving types, countries, start_date, and end_date bare. The description compensates by explaining the semantics of mode, series, and the country/type breakdown, but not the undocumented date/country/type filters.

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 resource (one app's featuring history) and splits it into two well-defined modes: creatives (every featuring with position and download attribution) versus impacts (aggregated occurrences and downloads by country or type). That is a specific verb+resource statement. It does not explicitly contrast itself with the sibling sensortower_featured (non-history), so it stops short of full sibling differentiation.

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

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

It clearly routes between the two modes and gives the condition for series=true ('its *_series arrays carry NO dates... so set series=true to have them zipped back onto real dates'). It also warns that invalid filters yield a 200 with empty arrays, which is actionable usage context. No explicit 'do not use this when...' versus sibling tools is 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 already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuine behavioral value by disclosing the incompatible parameter combination per mode, but says nothing about response shape beyond the sketch, rate costs, or 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?

Two dense sentences with no redundancy, and the primary mode is front-loaded with the parameter constraint. The telegraphic style is slightly cryptic but wastes no words.

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 13-parameter tool with no output schema, the description covers the pivotal mode parameter and gives a rough output sketch per mode, but omits the tool's overall purpose, selection guidance versus siblings, and any explanation of the remaining undocumented parameters.

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

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

Schema coverage is 69%, and several parameters (mode, app_ids, keywords, date_granularity) carry no schema description. The description partially compensates by defining what mode values yield and by warning that metric= (not bundle=) is required, but it leaves the other undocumented parameters unexplained.

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

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

The description explains what each of the two modes returns (per-keyword-per-day metric vs rank-bin counts), which conveys the resource, but it never states the tool's overall purpose: returning historical keyword rank/traffic for apps over a date range. It reads as mode documentation rather than a purpose statement, and the sibling differentiation is only a passing hint ('NOT bundle=').

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 one embedded usage rule - metric= applies to mode=timeseries and bundle= does not - but no explicit guidance on when to choose this tool over siblings like sensortower_keywords, nor when to pick timeseries vs rank_overview. The agent must infer selection criteria.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds a genuine behavioral nuance beyond the annotations: the default ordering (est_keyword_downloads:desc) applied automatically and the underlying bundle's alphabetical default. It omits rate/charging behavior, though the schema's dry_run description covers the 0-request path.

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 with essentially no filler, and the primary mode (by=keyword) is front-loaded. The inline bundle references are slightly noisy but serve as useful cross-references, keeping it just short of a 5.

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

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

For a 14-parameter, high-coverage schema with no output schema, the description covers the key routing parameter and an important default that the schema alone does not surface. It leaves output shape unstated, but as a filtered query tool returning rows that gap is minor.

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 high (86%), so the baseline is 3, but the description goes further by explaining the semantics of the 'by' parameter (the single most important branching input) in terms of the question each value answers. It does not add field-level meaning beyond the schema, hence not a 5.

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

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

The description clearly frames the tool's dual purpose by mapping each enum value of 'by' to a concrete question it answers ('which apps rank for this term' vs 'which terms does this app rank for'). It communicates the resource (ASO keyword/app keyword research) precisely, though it never gives a plain headline statement of the tool's overall job and relies on bundle jargon for context.

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

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

It explicitly tells the agent when to use each mode: by=keyword for ranking apps on a term, by=app for terms an app ranks for. It also pre-empts a common pitfall by stating that this tool always sends order_by=est_keyword_downloads:desc unless overridden, so the agent knows the default behavior without re-deriving it.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. Beyond that the description adds real behavioural context: the mapping of each metric value to the underlying bundle and the resulting payload (downloads/revenue vs active users/time spent), plus the side condition on date_granularity. It does not mention request charging or pagination, but dry_run's cost behaviour is already in the schema.

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

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

Three dense sentences, front-loaded with the core scope before the metric semantics and the date_granularity caveat. No filler or restatement of the name. Slightly telegraphic, but every clause carries information an agent needs.

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

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

For a 14-parameter aggregation tool with no output schema, the description covers the essentials: what is aggregated, which metric produces which measures, and the date_granularity requirement. It does not describe the shape of the returned rows, though the metric explanation partially compensates and no output schema exists. Adequate without being exhaustive.

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 coverage at 71%, the description usefully supplements what the schema lacks: it explains what metric=store vs metric=usage actually returns, gives examples for breakdown, and states the date_granularity dependency that the schema only implies. This adds meaning beyond the raw enum/description text. Undocumented params such as regions and the category filters are left unexplained by both sources.

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 and scope: 'Market-wide totals sliced by a dimension', which implicitly separates it from app-level siblings like sensortower_app_estimates or sensortower_top_apps. It enumerates the usable dimensions (category, region, device, genre, art style), so the agent knows what the tool produces. It never names a sibling explicitly, so it falls just short of full differentiation.

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

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

Gives concrete conditional guidance: metric=store yields downloads/revenue while metric=usage yields active users/time spent, and it warns that any breakdown ending in ',date' requires date_granularity. This is clear usage context and prevents an obvious misuse. It does not state when to prefer this tool over a sibling aggregation tool, nor any exclusions, 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 and openWorldHint=true, so the safety profile is covered. The description adds nothing behavioral beyond that: no mention of request/quota cost (which the schema's dry_run hints exists), no return shape, no pagination or row-width caveats.

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

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

Three short sentences, front-loaded with what the data is, then the one parameter distinction that matters, then the failure mode to avoid. No filler.

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

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

With 11 parameters, no output schema, and a breakdown/date_granularity interaction the schema only half-documents, the description covers only the bundle enum. An agent still lacks the returned column shape and the breakdown granularity contract.

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 64% and the bundle parameter has no schema description, so the description meaningfully fills that gap by explaining incremental vs cumulative semantics and warning that plain `ratings` is invalid. However, it says nothing about the other nine parameters (breakdown, date_granularity coupling, regions, fields, format, 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 the resource and the payload ('Rating counts and averages') and clarifies it is a time-series ratings feed, which distinguishes it from sensortower_reviews (review text) and sensortower_review_breakdown. It is a noun phrase rather than a verb, but the intent is 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?

There is no guidance on when to choose this tool over sensortower_reviews or sensortower_review_breakdown, nor any statement of prerequisites beyond the required app_ids/date window implied by the schema. The bundle discussion is parameter semantics, not usage 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 only cover readOnlyHint and openWorldHint, so the description carries the rest and does so well: it discloses that auth, token redaction, gzip and retries are handled internally, that calls consume request quota (dry_run charges 0), and that artwork is stripped by default. It stops short of describing error behavior beyond the 422 case or pagination/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-loaded with the 'Escape hatch' framing, then behavior, then routing rule, then caveat, then tip. Every sentence adds something an agent needs; no filler or restated schema text.

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

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

For a raw passthrough GET with no output schema, the description supplies everything needed: what it returns ('raw JSON back'), what is handled for you (auth, redaction, gzip, retries), the quota implication of dry_run, and the default payload trimming. Nothing material is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description largely restates what the schema already documents (dry_run, artwork dropping) and only adds the non-obvious hint that a deliberately bogus enum value surfaces valid values via the 422 response.

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 ('any SensorTower path with arbitrary query parameters, raw JSON back') and positions itself explicitly as the 'escape hatch' for the ~50 endpoints lacking a dedicated tool, naming concrete categories (ad creatives, network analysis, churn, cohort retention). An agent can distinguish it from the ~28 sibling tools without opening any schema.

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

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

Gives an explicit use condition ('use this for the ~50 endpoints without a dedicated tool'), an explicit exclusion ('Do NOT pass auth_token'), and a discovery tactic for enum values via the 422 body. When-to-use, when-not-to, and the alternative (dedicated tools) are all stated.

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

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

Annotations already cover readOnly/openWorld=false/idempotent, so the bar is lower; the description adds value by confirming 'Entirely offline: 0 requests' and disclosing that the static JSON files the contract links to are dead. It could say more about output size/shape, but the extra behavioral context is genuine 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?

Front-loaded with content scope, then the facets mapping, then the offline/usage note. It is dense but each clause carries distinct information; slightly packed but no filler 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 zero-request static reference tool with a single fully-documented enum parameter, the description covers content, usage, and the offline guarantee adequately. No output schema is needed for a vocabulary dump, though a hint on output size/shape would have made it complete.

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

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

Schema description coverage is 100% with an enum on the single `section` parameter, so the schema already documents the narrowing options fully. The description does not add meaning beyond the schema for `section`, so the baseline 3 applies.

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

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

States a specific resource (offline vocabularies: category ids, chart types, ad networks, tags, sentiments, keyword types, audience formats, metric-to-breakdown table) and its use. It clearly distinguishes itself from the data-fetching siblings by being the enum/reference source, and even explains the facets path-key mapping. An agent can tell exactly what it gets.

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

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

Explicitly instructs 'Read this before guessing an enum' and warns that linked /api/docs/static/*.json files are dead, giving a concrete when-to-use trigger and when-not (don't guess, don't chase the dead static files). The zero-request note reinforces that this is the cheap, safe lookup path.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered and the description does not contradict it. The description adds no behavioral context beyond the parameter semantics (no mention of request cost, pagination, or result shape), so with annotations present a 3 is appropriate.

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

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

Three tight sentences, front-loaded with the core action, then the by-value interpretations, then the prefix mechanics. No filler, and the opening verb+resource is immediately scannable.

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

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

For a 12-parameter tool with no output schema, the description resolves the two most ambiguous parameters (by, prefix) but leaves the return shape as merely "counts" and says nothing about the other parameters, which rely on 67% schema coverage. Adequate for the core decision but not complete.

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

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

With schema coverage at 67%, the description still adds real meaning: it explains what `by` values answer and, crucially, the `prefix` concept ("a plain breakdown or one prefixed with date, region, language or app_version") that the schema only lists as an enum. This is meaningful value beyond the structured 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+resource ("Aggregate review counts") and clarifies what each `by` value delivers, which is more than a name restatement. It does not, however, differentiate itself from the adjacent siblings sensortower_reviews and sensortower_ratings, so the agent must infer that this is the aggregated/breakdown variant.

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 mapping of by=rating/sentiment/tag to plain-English questions ("how do the stars break down", "how happy are they") is genuinely useful selection guidance for the key enum. But there is no explicit when-to-use-this-vs-alternatives and no exclusions, so it remains implied usage rather than 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 cover the safety profile (readOnlyHint, openWorldHint), so the bar is lower, and the description still adds a real behavioral fact: the API's large parsed_content token dump is stripped from the returned rows. It also flags that the filter vocabularies are not enumerable from the contract. It doesn't mention pagination or result-size 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?

Two sentences, no filler, with the payload description front-loaded and the field-drop caveat following. The second sentence packs filtering guidance and the reference pointer densely but every clause carries information.

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

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

For a 15-parameter, no-output-schema tool with only light annotations, the description covers the important output caveat and the filter vocabulary dependency but omits pagination semantics for page/limit and gives no sense of result volume. Adequate to call correctly, incomplete for callers who need to page or budget tokens.

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 60%, so several parameters (page, end_date, versions, search_term, app_id) rely on name alone. The description adds meaningful context for the filter params (tags, sentiments, rating_filter) by pointing to sensortower_reference for allowed values, but does not compensate for the undocumented remainder.

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 its per-review contents (rating, sentiment, tags, version, language), which is specific enough to separate it from aggregate siblings like sensortower_review_breakdown and sensortower_ratings. It stops short of an explicit 'returns individual user review rows' framing, but the scope is 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?

It tells the agent how to narrow results (tags/sentiments/rating_filters) and routes vocabulary lookups to sensortower_reference, which is useful. It never states when to choose this over the aggregate review siblings, so the routing guidance is only partial.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real behavioral context beyond that: the iOS-only constraint and the data-shape quirk that by=history returns a dict keyed by app-id string that is flattened here. It omits cost/rate-limit behavior, though dry_run is documented in the schema.

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

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

Three parallel, front-loaded clauses map one-to-one onto the enum values, followed by a single constraint sentence. No filler, no repetition of structured fields, and the highest-value information (mode semantics) comes first.

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 10-parameter read-only query tool with no output schema, the description covers the hardest gap (undocumented enum semantics), the platform limitation, and a known response-shape gotcha. Nothing essential to correct invocation appears to be 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 'by' enum values are completely undocumented in the schema, and the description is the only place their semantics are defined; it also restates the conditional requirements for term and app_id. The remaining parameters (fields, format, limit, country, dry_run, dates) are left to the schema, which covers them at 70%.

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

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

The description names the specific resource (Apple Search Ads share of voice) and enumerates the three distinct query modes (by=term, by=app, by=history) with a one-line statement of what each returns. An agent can tell what it does without opening the schema, though it does not explicitly differentiate itself from siblings like sensortower_keywords or sensortower_top_advertisers.

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 selection guidance by mapping each mode to an intent: 'who is buying ads on a search term' vs 'which terms an app buys' vs 'one app's daily share of voice on one term'. It also states the platform boundary (iOS only, no Android equivalent). It stops short of naming when to prefer a sibling tool instead.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: games=true silently redirects to the games_breakdown endpoint with the same shape, and revenue is converted from cents. It omits any cost/rate-limit note despite dry_run existing in the schema.

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

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

Three sentences, front-loaded with the core purpose, then the games branch, then the units note. Mostly earns its place, though the games-endpoint sentence partly duplicates the schema's games field description.

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, 11-param tool with no output schema, the description covers purpose, endpoint switching, and unit conversion. It stops short of describing the return shape beyond 'same shape,' but the annotations carry the safety profile, so an agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description only marginally adds value: the games endpoint switch is already documented in the schema's games field, while 'revenue converted from cents' is the one genuinely new semantic detail not present in any parameter description.

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

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

States a specific verb+resource ('Category-level download and revenue totals over time') and immediately disambiguates scope: 'the whole category, not per-app.' This cleanly separates it from the many app-level siblings (app_estimates, app_active_users, etc.) without opening a schema.

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

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

The 'not per-app' clause implies when to reach for app-level siblings instead, and it explains the games=true branch. However it never names a specific alternative tool or states explicit exclusions (e.g. vs market_size), so routing relies partly on inference.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety bar is covered. The description adds real behavioral context beyond that: the app_id mode returns page, rank and sov, and the notable gotcha that 'Facebook' is rejected here but valid on network_analysis. No rate-limit or auth detail, but for a read tool this is solid.

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

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

Four tight sentences, front-loaded with the core purpose before the mode switch and the vocabulary caveat. Every sentence is load-bearing and none restate the schema.

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

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

For a 14-parameter tool with no output schema, the description covers purpose, the two operating modes, key return shape (page, rank, sov), and a vocabulary pitfall. Remaining details (pagination limits, field selection, dry_run) are handled in the schema, so the definition is nearly complete but not exhaustive.

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 71% schema coverage the schema does most of the work, giving a baseline of 3. The description earns the extra point by explaining the semantics of role (advertiser=buying vs publisher=showing) and app_id (single-app rank lookup) rather than just restating names.

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 and verb: a share-of-voice leaderboard scoped to a network and category. It clarifies both modes (full board vs single-app position) and defines role semantics, so the agent knows exactly what it produces. It does not explicitly differentiate itself from the sibling sensortower_top_publishers, which is the one gap keeping this from a 5.

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

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

Gives clear when-to-use guidance: role=advertiser for buyers, role=publisher for publishers, and supply app_id to switch from whole-board to single-app lookup. It also flags the per-endpoint network vocabulary constraint. No explicit when-not here, but the alternatives are well covered.

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

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

Goes well beyond readOnlyHint and openWorldHint by disclosing that revenue is returned in cents and converted to *_usd, that the 213-key custom_tags blob making up 94% of each row is dropped unless requested, and that iOS device_type defaults to iphone. These are non-obvious output and defaulting behaviors. It stops short of covering pagination behavior (offset/limit interactions) or error modes.

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 dense sentences, each carrying a distinct behavioral fact (routing, cents conversion, blob dropping, iOS default). No filler, and the measure-routing rule is front-loaded. The unusual multi-clause sentences are justified by the density of 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 16-parameter read-only tool with no output schema, the description covers the highest-value surprises: measure-based endpoint switching, currency conversion, cost/width of custom_tags, and the iOS device_type default. It omits any coverage of limit/offset/pagination semantics and end_date behavior, which is a gap for a leaderboard tool that expects date ranges.

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

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

Schema coverage is 75%, and the schema itself already documents many parameters. The description adds real value for measure routing and device_type defaults, but it doesn't address the remaining parameters like limit, offset, time_range, comparison_attribute, resolve_names, dry_run, or format beyond what the schema says. Baseline 3 given the partial schema coverage and mixed added value.

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 exact resource (the estimate-based leaderboard) and splits behavior by measure value, distinguishing the sales-estimate leaderboard from the active-user leaderboard. This is a precise verb+resource framing that sets it apart from sibling tools like sensortower_top_charts or sensortower_app_estimates.

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 internal measure routing and notes iOS device_type is de-facto required, which implies when certain options must be set. However, it never says when to choose this tool over siblings such as sensortower_top_charts, sensortower_app_estimates, or sensortower_app_active_users. Usage is implied rather than explicitly contrasted with 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?

Annotations already cover the safe-read profile (readOnlyHint, openWorldHint), and the description usefully adds that the raw API returns bare app ids with no names or rank numbers while this wrapper injects both, plus the plain-text 422 error format. It stops short of describing pagination, auth, or how limits interact with resolve_names.

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

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

Three tight sentences: what it returns, what the wrapper adds, and how to get valid enum values. Front-loaded with the identifying information and no wasted clauses.

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 10-parameter, no-output-schema tool, the description supplies the return-shape details (rank-ordered bare ids plus added names/rank numbers) and the error behavior that the schema cannot. Nothing essential for correct invocation is missing.

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

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

Schema coverage is already 100%, so the baseline is 3; the description elevates it by explaining where valid category/chart_type values come from (sensortower_reference) and by flagging the store-specific nature of the endpoint. It adds a little meaning beyond the schema's own parameter 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?

States a precise verb+resource: the App Store / Google Play top chart for a given category, country and date, and notes it targets a single store rather than a unified endpoint. It does not explicitly differentiate from nearby siblings like sensortower_top_apps or sensortower_top_publishers, so it stops short of 5.

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

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

Gives a concrete routing instruction: fetch valid category and chart_type values from sensortower_reference, and warns that a bad value produces a 422 in plain-text form. It offers no guidance on when to prefer this chart tool over sibling ranking tools, so it lacks an exclusion 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 readOnlyHint and openWorldHint, so safety is covered. The description adds genuinely useful non-annotation context: responses are large and asset-URL heavy, which justifies the fields/limit advice. It does not mention request cost/credits (only the schema does, via dry_run), so the addition is real but thin.

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 with zero waste: purpose first, actionable tuning advice second. Nothing is redundant with the title or schema.

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

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

For a 12-parameter read tool with no output schema, the description covers the two things an agent most needs to know up front: what the endpoint returns and that responses must be trimmed. Missing pagination behavior and cost framing are minor since the schema documents page/dry_run.

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 67%, so the schema carries most parameter meaning. The description adds only a rationale for two of twelve parameters (fields, limit) and says nothing about date, period, country, page, or ad_types, leaving the partial coverage gap only partly compensated.

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 (ad creatives) with a clear scope qualifier ('most-seen', 'for a network and category'), which separates it from siblings like sensortower_top_advertisers and sensortower_search_ads. It never names an alternative tool explicitly, 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?

The advice to 'use fields/limit aggressively' is operational tuning, not selection guidance. There is no statement of when to prefer this over sensortower_top_advertisers or sensortower_raw_get, and no prerequisites (e.g. that network/category/date are mandatory) are called out.

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

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

Annotations already cover the safety profile (readOnlyHint, openWorldHint). The description adds genuine structural context beyond annotations: each row nests an apps[] array and custom_tags is stripped at both levels unless keep_custom_tags is set. This is useful output-shape disclosure.

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

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

Two tight sentences, front-loaded with the resource scope before the nested-output caveat. No waste, though the double-em-dash clause is slightly dense.

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 15 parameters and no output schema, the description should carry more weight for output interpretation. It discloses the nested apps[] shape and custom_tags stripping, which is helpful, but ignores return-value semantics for the delta/transformed_delta comparison modes and many params.

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 roughly a third of parameters are undocumented in the schema. The description only clarifies keep_custom_tags behavior and implies a units/revenue choice via 'downloads or revenue', leaving most params (measure, format, comparison_attribute) to the schema. Baseline 3.

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

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

States a specific verb+resource: 'Publisher-level leaderboard by downloads or revenue.' The 'publisher-level' qualifier implicitly distinguishes it from app-level siblings like top_apps/top_charts, though it never names them explicitly.

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

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

The description gives no when-to-use guidance, no prerequisites, and no routing to alternatives such as top_apps or top_charts. An agent must infer the use case from the resource name alone.

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