OpenApps

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds behavioral context beyond that: results are ordered newest-first and include counts per change type. It omits pagination behavior (the cursor param) and any note on result size, which keeps it from a 5.

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

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

Two sentences, zero filler. The positive usage condition and the returned shape come first, the exclusion and sibling redirect second — exactly the right front-loading.

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 9-parameter, read-only list tool with no output schema and only 56% schema description coverage, the description covers what the tool returns and when to use it, but leaves pagination (cursor/limit) and the response_format/context params entirely to an incomplete schema. Adequate but with clear gaps.

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

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

Schema coverage is 56%, so it sits near the baseline where the schema does most of the work. The description does add value by naming the concrete change-type vocabulary the `types` filter operates on and framing the store scope, though it says nothing about limit, cursor, region, or response_format.

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 (list changes in a store) and enumerates the change categories (chart moves, featuring, launches, delistings, metric moves, MCP changes) plus the ordering (newest first). This is enough for an agent to distinguish it from charts_get and other siblings without opening either schema.

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

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

Gives an explicit when-to-use trigger ('user asks what changed in a store') and an explicit when-not with a named alternative: 'Do not use for a chart's full current order; use charts_get.' Nothing is left to inference.

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

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

Annotations already establish that this is a safe read-only operation with no open-world side effects. The description adds useful behavioral hints about historical access and output shape ('movement and 1-based positions'), but does not cover pagination, rate limits, or other operational details.

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 two-sentence structure is tight and front-loads the usage guidance. There is no wasted text, though the phrasing is slightly opaque in places.

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 9-parameter tool with no output schema, the description is thin. It hints at output semantics but omits important context such as pagination (limit/cursor), response format, and how store, region, and context parameters affect behavior.

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

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

Schema description coverage is only 56%, so the description should compensate for undocumented parameters like limit, cursor, context, response_format, and store. Instead, it gives almost no parameter-level guidance beyond the implied 'at' time behavior and does not clarify the undocumented fields.

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

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

The description frames the use case as needing 'a chart now or at a past time, with movement and 1-based positions,' which implies retrieval but does not state a clear verb or what kind of chart data is returned. It does distinguish the tool from listings_profile, which helps, but the core purpose remains somewhat vague.

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 says when to use it ('when you need a chart now or at a past time') and when not to use it ('Do not use for a listing across charts; use listings_profile'). The alternative is named directly, leaving little 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 cover the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower, but the description still adds a real constraint not present in structured data: the 30-day maximum lookback window. It does not disclose pagination behavior despite a cursor parameter, nor does it say how results are ordered or capped by limit.

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 waste. The primary use case is front-loaded and the exclusion/alternative follows immediately, so an agent scanning the description gets the routing signal before any detail.

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

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

For a 10-parameter, no-output-schema read tool, the description covers purpose, scope limit, and sibling routing, but leaves pagination (cursor), result-count behavior (limit), and the purpose of context/response_format unexplained. Adequate to call the tool correctly in the common case, but not complete for the full parameter 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?

With 60% schema coverage and 10 parameters, the description contributes meaning for the app/chart split ('per app or home shelf') and reinforces the time-window constraint on since/at. However, cursor, limit, context, and response_format get no treatment in either the description or (for two of them) the schema, so it only partially compensates for the coverage gap. Baseline 3 for moderate coverage 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 names the specific resource (featuring history: when and where apps were featured), its two axes (per app or home shelf), and its time scope (at most 30 days). It also explicitly differentiates from the sibling charts_get, which handles current shelf order. It falls just short of a 5 because the phrasing is grammatically awkward ('need when and where') and never states that the result is a historical timeline rather than a point-in-time snapshot.

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?

Both halves of the routing decision are explicit: 'Use this when you need when and where apps were featured... over at most 30 days' and 'Do not use for current shelf order; use charts_get.' The agent gets a positive trigger, a negative trigger, and the named alternative in two sentences.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false), it discloses that reports are stored privately under the caller's account and client, that no reply arrives in this conversation, that user consent is required for unsolicited reports, and that secrets/PII must be excluded. These are material behavioral traits an agent cannot infer from the schema or annotations.

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

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

Four tight sentences, front-loaded with the usage triggers, then consent, privacy, and exclusions. Nothing is wasted, though the opening sentence could be sharper about the core action.

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

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

For a write tool with 8 parameters, no output schema, and safety annotations already present, this covers most of what an agent needs: triggers, exclusions, consent, privacy, and content restrictions. The remaining gap is detailed guidance on the technical parameters (request_id, subject_id, subject_type), which the description leaves entirely to the schema.

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

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

Schema coverage is 50%, and the description only indirectly touches two fields ('Summarize' for summary, 'never include secrets' for details). It provides no guidance on 'tool', 'issue', 'subject_id', 'subject_type', or 'request_id', leaving half the parameters to the schema alone. Baseline 3 for moderate coverage with partial compensation.

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 makes clear this is a feedback-reporting tool for OpenApps failures, and explicitly scopes it away from other servers or the client app. It never states the action as a crisp verb+resource ('sends a report to OpenApps') up front, relying on implication, but the purpose is unambiguous in 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 gives explicit triggers (errors, wrong data, missing capability, confusion), an explicit exclusion (other servers, client app, task completion), and a consent rule ('Ask the user before sending a report they did not ask for'). This is exactly the when/when-not/alternatives 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 already declare readOnlyHint=true and openWorldHint=false, so safety and scope are covered structurally, and an output schema exists so return shape need not be described. The description adds the useful constraint that ids must originate from search results. It says nothing about failure behavior for stale or malformed ids, or whether the document is returned in full or truncated — modest value on top of annotations.

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

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

Two short sentences, front-loaded with the use case followed by the exclusion — nothing redundant. The 'ChatGPT deep research' framing is slightly client-specific phrasing that costs a little clarity without adding information, 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?

With one parameter, full schema coverage, annotations declaring read-only/local scope, and an output schema defining return values, the definition supplies nearly everything an agent needs to invoke it correctly. The only material gap is disambiguation from the entity-specific getter siblings, which the description leaves unaddressed.

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

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

Schema description coverage is 100% and the single id parameter's schema already enumerates every prefix form (listing:{store}:{plugin_id}, app:{slug}, tag:{id}, chart:{store}:{chart}, server:{url}). The description restates the same type list without adding format rules or edge cases, so the schema is doing the work. Baseline 3 applies.

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

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

The description does name the resource — a document for an id of type listing, app, tag, chart, or MCP toolset — so the agent gets more than the bare verb 'fetch'. However, it frames the purpose around 'ChatGPT deep research' rather than the general operation, and it never distinguishes itself from siblings like charts_get, mcp_toolset_get, or listings_profile that appear to retrieve the same entity types by id. The purpose is inferable but not crisp.

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

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

It gives a clear precondition ('when ChatGPT deep research needs a document for an id returned by search') and an explicit exclusion ('Do not use for ids outside search results'). That is genuine when/when-not guidance. What it omits is routing against the near-duplicate siblings — an agent holding a chart id has no signal whether to call fetch or charts_get.

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

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

annotations already declare readOnlyHint=true and openWorldHint=false, so safety and scope are covered by structured data. The description adds domain context — that metric names are store-specific and enumerable — which is genuinely useful. It says nothing about result size, pagination via cursor/limit, or ordering, which are the behaviors an agent would still need to discover.

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 compact sentences, the trigger front-loaded and the exclusion last, with no filler. The 'claude: installs, ...' shorthand packs information densely but is slightly cryptic and hardcodes only two of the six enum stores.

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 seven-parameter read-only tool with no output schema, the definition covers the selection decision and metric vocabulary, which is the core need. Gap: it omits pagination and response_format semantics.

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

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

Schema coverage is only 43% (store, limit, cursor and response_format are undocumented in the schema), so the description has to carry weight. It partially compensates by enumerating valid metric names for two stores, which is meaningful since metric is a free-form string. But it leaves the other four stores' metrics, plus cursor, limit and response_format, entirely 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?

It conveys a specific operation — ranking apps within a store by a published metric — and names concrete metrics per store, so the agent knows what the tool returns. It also names the sibling it is not (charts_get). The word 'leaderboard' never appears explicitly, so the purpose is inferred from 'which apps lead a store', which is clear but one step short of a direct verb+resource statement.

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

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

Explicit positive trigger ('use this when the user asks which apps lead a store by a published number') and an explicit exclusion with a named alternative ('Do not use for chart positions; use charts_get'). That is the full when/when-not/alternative triple, leaving nothing to inference.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), so the description's added context is what matters: a 5-item batch cap on Pro plans and the behavior for 'stale or refused countries' (they read unknown). That is genuinely useful call-time behavior, though nothing is said about auth requirements, rate limits, or how partial failures across multiple apps are surfaced.

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 immediately followed by the exclusion rule. The batch-limit qualifier and the unknown-state caveat are compressed tightly 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?

With no output schema, the description carries the burden of explaining what comes back, and it does so by listing the profile sections, plus it flags the batch cap and the unknown-country behavior. Minor gaps remain around multi-app failure handling and how to interpret the concise versus detailed formats.

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 largely documents the parameters; the description only echoes the section names (ranks, metrics, tools) that already exist as an enum in 'include'. It adds nothing about the 'apps' ref format, the 'context' goal field, or when to choose response_format=detailed versus concise.

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 (a listing profile) and enumerates exactly what comes back: app, country availability, ranks, metrics and MCP tools. It also states the batch scope (up to 5 on Pro) and explicitly distinguishes itself from the discovery-oriented sibling listings_search.

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

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

It gives an explicit trigger ('Use this when you need a listing profile') and an explicit exclusion with a named alternative ('Do not use for discovery; use listings_search'). An agent has a clear routing rule without needing to read either schema.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful result-shape context ('one row per app, best match first'), but says nothing about result volume, pagination via cursor, or how the context parameter influences matching.

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

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

Two tight sentences with the positive condition first, result shape second, and the exclusion last. Zero wasted 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 an 8-parameter, 3-enum search tool with no output schema, the description covers the core query intent and result cardinality but omits how to page (cursor), how limit interacts with results, and what the store/kind enums mean for narrowing. An agent must fall back to the schema for roughly half the invocation surface.

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

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

Schema description coverage is 38% across 8 parameters, so the description must compensate and largely does not. It enriches the query parameter with a concrete example ('create jira ticket') but leaves kind, store, limit, cursor, context, and response_format entirely undocumented in both places.

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

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

It states a concrete retrieval task: resolve an app's ref from its name, publisher, brand, or function, and it explicitly contrasts with charts_get. The verb is implicit ('use this when you need an app's ref') rather than a clean 'search listings', but the resource and scope are unmistakable.

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

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

Two explicit rules: use it when you need an app ref from vague identifying cues, and do NOT use it for popularity or rankings — use charts_get instead. This is a direct when/when-not/alternative structure naming the sibling.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and locality are covered. The description adds the data-domain scope but says nothing about data freshness, source coverage, or whether results are truncated across the six stores. Adequate but thin for a stats tool with no output schema.

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

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

Two sentences, no filler, with the positive use case front-loaded before the exclusion. Every clause earns its place.

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

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

With no output schema, the description is the only place the return shape can be sketched, and it does so only as a loose list of topics. It leaves open whether all categories are returned together, whether output differs by response_format, and how the optional parameters affect the result.

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

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

Schema coverage is only 33% and the description explains none of the three parameters. It never says that `store` scopes results to a specific storefront (or what happens if omitted), nor what distinguishes `response_format: concise` from `detailed`. With low coverage the description was expected to compensate and does not.

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

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

The description names the concrete data categories the tool returns (store sizes, weekly launches, app kinds, MCP ecosystem statistics), which tells an agent what 'market' actually means. It stops short of a clean verb+resource statement, but the enumeration makes the resource identifiable.

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

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

It gives an explicit use condition ('when you need store sizes, weekly launches...') and an explicit exclusion ('Do not use for app profiles or rankings'), which implicitly routes to listings_profile and leaderboards_get. The alternatives are not named directly, so the routing is slightly inferential.

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

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

The annotations already mark this as a read-only, non-open-world operation. The description adds meaningful scope context: it only works with tracked servers and not arbitrary URLs, and it explains that at selects a snapshot while diff_from compares versions. It does not cover error behavior or authentication requirements, but those are not critical here.

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

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

The description is short and front-loaded: usage condition first, parameter semantics next, and exclusion last. Every sentence adds useful information without repetition.

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

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

For a read-only retrieval tool with no output schema and six optional parameters, the description covers the main usage modes, scope restriction, and snapshot/diff selection well. It could say more about default behavior when no app/server is supplied or about returned data shape, but the essential invocation guidance is present.

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 high (83%), so the schema already documents most parameters. The description adds conceptual semantics for at ('selects a past snapshot') and diff_from ('compares versions') beyond the schema's brief field descriptions, though it does not explain app, server, context, or response_format.

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 clear resource and scope: it retrieves stored MCP tools or changes for a tracked app or server. It distinguishes itself from arbitrary URL fetching, though it does not explicitly differentiate from any sibling tool by 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 gives an explicit use case ('when you need a tracked app or server's stored MCP tools or changes') and an explicit exclusion ('Do not use for arbitrary URLs'). It also explains the at and diff_from modes, but does not name alternative tools for related tasks.

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

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

With readOnlyHint=true and openWorldHint=false already declared, the safety profile is covered, and the description usefully disambiguates the two sort modes as "launch date" vs "the day each went live." It says nothing about pagination (limit/cursor), default window behavior, or the shape/size of results, which matter for a 9-parameter listing call.

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 waste, with the positive case stated first and the exclusion second — exactly the order an agent needs to make a routing decision. Nothing is repeated from the schema or annotations.

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

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

There is no output schema, so the description is the only source of expectations about results, yet it says nothing about result volume or paging. For a 9-parameter tool with sub-50% schema coverage, an agent is left guessing how to page through a long "new since" window.

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

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

Schema description coverage is only 44%, so the description must pull weight — and it does for `sort`, translating released_at/first_seen_at into plain language that the bare enum would not convey. However, `limit`, `cursor`, `response_format`, and `store` have no descriptions anywhere and are left unexplained, so the coverage gap is only partially closed.

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 (apps in a store) and the scoping dimension (new since a given time, ordered by launch date or first-seen date), which is specific enough to separate it from a generic listing tool. It never uses an explicit verb like "list," but the intent is unmistakable. Sibling differentiation comes entirely from the next sentence rather than from the purpose statement 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?

It gives a clear trigger (user asks which apps are new in a store since a time) plus an explicit exclusion with a named alternative: "Do not use for rank or toolset changes; use changes_list." What's missing is routing for the adjacent cases an agent will actually hit — e.g. finding a specific app by name, which presumably belongs to listings_search.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the aggregation window (28 days) and the shape of what comes back (tier, momentum). It stops short of describing pagination or result-size behavior for a 6-parameter list tool, so not a 5.

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

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

Two sentences, zero waste, with the primary usage trigger front-loaded and the negative routing compressed into a single clause. Every sentence earns its place.

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

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

For a read-only, 6-parameter list tool with no output schema, the description covers purpose, routing, and a hint of return shape, but leaves pagination (limit/cursor) and the chart-vs-store relationship unexplained. Adequate to select the tool, insufficient to invoke it confidently at scale.

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

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

Schema description coverage is only 33%, so the description must carry the load, and it does not. Only 'store' is obliquely implied ('in a store'); limit, cursor, context, and response_format are documented in neither the schema nor the description, and the description never explains that 'chart' must be discovered via stores_get.

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 concrete resource (OpenApps Rank), its exact semantics (a 28-day aggregate of popularity charts, with tier and momentum), and the user question it answers. An agent can distinguish it from every sibling without opening a schema.

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

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

Explicitly states the selecting condition (user asks which apps are popular in a store over the last month) and names two exclusions with their tools: charts_get for a single day's chart order, leaderboards_get for published counts. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description still earns credit for domain-specific behavior beyond the annotations: the `tag:<id>` query convention and the fact that results carry typed ids intended for a follow-up `fetch` call.

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

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

Two sentences, front-loaded with the usage trigger, then the return shape, then the exclusions. No filler and no restatement of the tool name.

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

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

The tool is simple (one param, annotations present, output schema available), and the description covers trigger, exclusions, query syntax, and result chaining. The remaining gap is routing against the near-duplicate `listings_search` sibling, which an agent facing 14 siblings would want resolved.

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 a single parameter at 100% schema coverage, baseline is 3; the description exceeds it by documenting query syntax that the schema does not (the `tag:<id>` keyword form) and implying the free-text fields the query matches.

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 scope explicitly: listings, apps, tags, charts, and tracked MCP URLs, plus the chaining outcome ('returns typed ids for fetch'). It does not, however, differentiate this generic 'search' from the sibling `listings_search`, which by name covers overlapping ground — an agent could reasonably pick either.

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 both a when ('use this when ... needs listings, apps, tags ... charts or tracked MCP URLs') and explicit when-nots with named alternatives ('Do not use for rankings or events; use charts_get or changes_list'). The trigger clause is oddly narrow, framed around 'ChatGPT deep research', and never mentions the `listings_search` alternative.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral content: guide switches the tool into returning a playbook's steps, and store is required to resolve chart names. It does not say what a no-argument call returns, how response_format changes output, or what the guide steps look like.

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

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

Three short sentences, no filler, with the trigger and the exclusion both stated up front. The enum semantics are packed into a compact clause rather than a bulleted restatement of 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?

With zero required parameters and no output schema, the agent needs to know what a bare call returns and how the modes differ, and the description only answers half of that. It also leaves the boundary against charts_get ambiguous by advertising "charts" in its own scope while telling the agent to go elsewhere for rankings.

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

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

Schema coverage is only 25% (just context), so the description must carry the load, and it does for the two ambiguous parameters: it explains that store maps to chart names and spells out what each guide enum value means, which the schema does not. It leaves response_format totally unexplained and says nothing about default behavior when no parameters are sent.

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 never states a crisp verb+resource; it enumerates a grab-bag of things ("stores, app counts, countries, freshness, charts or metrics") and then pivots to a guide playbook, so the tool reads as several tools in one. It does name one sibling exclusion, but the overlap with charts_get is muddled by listing "charts" as something this tool provides.

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 both a when-to-use trigger and an explicit when-not ("Do not use for rankings; use charts_get"), and it explains the three guide modes with concrete scenarios (a store's week, compare apps, an MCP server's tools). The guidance is weakened by the vague catch-all opening clause, which could be read as an invitation to use this for almost anything.

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