AppTierList

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

With readOnlyHint and idempotent annotations already covering safety, the description adds genuinely useful behavior: under_review apps yield no tier or position for that category, and positions are never compared across categories. These are partial-result semantics an agent could not infer from annotations alone, though return formatting and error behavior are still not described.

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 focused sentences: the first front-loads what is returned and the scope, the second covers the under_review edge case, and the third states the cross-category constraint. Nothing is redundant or padded.

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

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

For a read-only comparison tool with no output schema and rich annotations, the description covers the key return fields, the omitted-list default, and two important behavioral caveats. It does not address what happens when a given app is absent from an explicitly requested category, nor does it mention the ten-app maximum, which are minor 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 50%, with the list parameter already described as a category slug whose omission means shared categories. The description reinforces the 'two or more apps' minimum and the shared-category default, but adds no new meaning about the keys format or the max ten apps, so it only partially compensates for the coverage gap.

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

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

The description states a specific verb ('compare') and resource ('apps'), and enumerates the returned dimensions (tier, position, score, components), so the operation is unmistakable. It does not explicitly differentiate itself from siblings like explain_ranking or get_app, which keeps it short of a 5.

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

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

Usage is implied by 'Side-by-side ... for two or more apps' and by the omitted-list default, and the under_review caveat adds practical context. However, there is no explicit guidance on when to use this tool instead of calling get_app multiple times or explain_ranking, and no stated exclusions or 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 declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds real value beyond them: it discloses the shape of the returned verdicts (reason, currency relative to the app's present listing and the category's present definition) and warns that missing_since means the app is off the App Store. It stops short of saying anything about response size, cost, or what happens for an unranked app.

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: the first front-loads the payoff (the ranking breakdown), the second delivers the safety caveat. The first sentence is a dense nested list that takes a moment to parse, but nothing in it 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?

With only two fully-documented parameters and no output schema, the description carries the burden of describing return content and does so in detail (score components, ranks, verdicts, history). The missing piece is guidance on which key form to prefer or what comes back when the app has no ranking at all.

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 'key' (app slug or numeric app_store_id) and 'list' (optional category slug) are already fully documented. The description's 'per category' hints at the list filter but adds no format, defaulting, or validation detail beyond the schema, so baseline 3 applies.

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

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

The description states a specific purpose (explaining why an app ranks where it does) and enumerates exactly what the explanation contains: score components per category, per-store ranks, judge verdicts, and change history. That content list implicitly separates it from siblings like get_app or recent_changes, but it never names an alternative explicitly.

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

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

Usage is only implied by the framing 'Why an app sits where it does' — an agent must infer that this is the tool to reach for when a ranking needs justification rather than raw app data. The one explicit directive is about downstream behavior ('do not recommend it or send anyone to its store_url' for delisted apps), not about when to pick this tool over a 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 establish the tool as a read-only, idempotent, non-destructive operation, so safety is covered. The description adds behavior the annotations don't: what each id prefix returns (compact members for a category ranking vs. the full app record) and that the payload lands in a 'text' field as JSON. It omits error behavior for invalid ids and any sizing or truncation cues for large records.

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 two short sentences with no filler, and the retrieval outcome is front-loaded in the first clause. The phrasing is compressed, though: 'One document by the id search returned' is slightly awkward and requires a second read.

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

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

For a single-parameter tool with no output schema, the description covers the essentials: where the id comes from, what each id form returns, and which field holds the JSON. It falls short of full completeness only because the shape of the returned record is left to discovery and failure modes are unaddressed.

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

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

Schema coverage is 100% and the single 'id' parameter is already documented with its two accepted prefixes. The description nonetheless adds semantics beyond the schema, explaining what the agent actually receives for each prefix. That pushes it above the baseline of 3, though it doesn't cover an invalid-id case.

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: fetch one document (a category ranking or an app record) using the id that search returned. It goes further than the title by explaining that 'list:<slug>' yields a category ranking with compact members and 'app:<slug>' yields the app's full record. It doesn't distinguish itself from the get_app / get_category siblings, which appear to retrieve similar objects by other keys.

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

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

The phrase 'the id search returned' implies the intended workflow: call this after search, using the returned ids. But it never states when to prefer this tool over get_app, get_category, or search_apps, nor what to do when the id is malformed or from a different source.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantive behavior beyond that: group membership is exclusive ('each app in one group at most'), each result carries a reason tag (shared_lists, same_genre, free), and all candidates come from the app's main-job category. It stops short of describing ordering stability 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?

Purpose is front-loaded, but the body is one long run-on sentence packed with nested parentheticals and semicolon-separated clauses. The information earns its place, yet the grouping definitions would be far more scannable as a short list than as a dense prose block.

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 the return shape and does so well: three named groups, exclusive membership, and per-item reason tags. The remaining gap is the default/limit behavior and whether `all` is truncated by `limit`, which an agent needs to interpret results correctly.

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

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

Schema coverage is 100% for both parameters, so the baseline of 3 applies; the description does not clarify `key` formats or how `limit` interacts with the `all` group. In fact, 'all lists every alternative' sits awkwardly against the schema's 'max apps in all (default 20)', leaving the agent to reconcile the cap itself.

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?

Opening clause names the exact resource: apps that do the same job as the given app, split into three named groups (most_similar, top_rated, best_free). This is clearly distinct from siblings like search_apps, compare_apps, and get_category, though it never names those siblings to sharpen the contrast.

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

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

The closing sentence gives one concrete usage trigger ('An app whose missing_since is set is no longer on the App Store: its alternatives matter most then'), which is genuinely useful. However, it offers no guidance on when to prefer this over search_apps or compare_apps, and no exclusions are stated, so usage is implied rather than spelled 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 (readOnly, idempotent, non-destructive, closed-world), yet the description still adds substantial semantics: null tier/position is explained per review_status and list_ranking_status, main_list is defined as derived from the placer's primary marking and explicitly 'never guessed', and the missing_since case carries an action-level warning. This is real behavioral context 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?

It is front-loaded correctly — the core purpose is the first six words — and most clauses carry non-obvious semantics that would otherwise be lost without an output schema. But it is delivered as one sprawling sentence with three-deep nested parentheses, which makes the field-level rules hard to parse on a first read.

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

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

With no output schema, the description correctly takes on the burden of explaining return-field semantics and the nullability rules that would otherwise mislead an agent. Gaps remain: what happens when the key matches nothing, and how far back 'recent history' extends, are unstated.

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

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

Schema coverage is 100% and the single parameter already documents 'app slug or numeric app_store_id'; the description only restates 'by slug or App Store id'. No format examples, no guidance on which key form is preferable when both exist. Baseline 3 is appropriate since the schema does the work.

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

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

The opening clause names the exact verb and scope: 'One app by slug or App Store id', which immediately separates it from multi-app siblings like search_apps, compare_apps, and find_alternatives. It then enumerates the payload (App Store facts, generated summary, category memberships, main_list, maker claim, history), so an agent knows precisely what it retrieves.

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

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

Usage is implied rather than stated: you call it when you already hold a slug or app_store_id, and the description never says how to obtain one (e.g., via search_apps) or when to prefer a sibling. The one explicit directive — do not recommend or link an app whose missing_since is set — is a genuine when-not rule, but it concerns interpreting the result rather than selecting the tool.

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

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

Far exceeds the readOnly/idempotent annotations: it explains under_review ordering and display rules, ranking_status thresholds ('under_review' vs 'too_few' vs fewer than 6 apps), the missing_since recommendation hazard, and merged-category slug redirection. This is exactly the behavioral context an agent needs to interpret the response correctly.

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

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

Front-loaded with what is returned, then conditional edge-case rules. It is dense and somewhat run-on, but virtually every clause carries distinct, actionable information about the payload semantics.

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

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

With no output schema, the description carries the full burden of explaining the response shape—member fields, the two app-summary variants, ordering, statuses, and special cases—and does so comprehensively. Nothing an agent needs to interpret a category response is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds a useful interpretive note by implying the whole tiered set is bounded (schema notes '40 is the whole tiered set' for limit). Marginal added value over schema but nothing contradictory.

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 the exact verb+resource ('tier list for one category') and enumerates the returned fields (tier, score, components, per-store ranks, confidence, verification). An agent can tell it apart from get_app (single app details, referenced explicitly) and list_categories (slug source) 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?

Routes the agent to get_app / api_url for full app details and to list_categories for the slug, and explains the within-category-only meaning of positions. It doesn't contrast against search or compare_apps, but the core usage conditions are clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds meaningful behavioral context by enumerating the specific health dimensions returned, including cool-downs and invariant status, which goes beyond what the annotations provide.

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

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

The definition is a single dense sentence that packs many metrics into a colon-separated list. It avoids waste, but the initial question format is slightly awkward and the list could be more skimmable; nonetheless, it is appropriately sized for a health-check tool.

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

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

With no output schema and no parameters, the description carries the burden of explaining what the tool returns, and it does so by enumerating the health indicators. It is nearly complete for invocation, though it does not describe the response structure or format beyond naming the metrics.

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

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

The tool has zero parameters, so parameter semantics are not a concern. The baseline for a parameterless tool is 4, and the description does not need to compensate for any schema gaps.

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

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

The description clearly identifies a system-health diagnostic and specifies the metrics it covers, including job success/due times, cool-downs, invariant checks, pending judgments, stale apps, and public_unchecked counts. It is distinguishable from all sibling tools, which focus on app search, comparison, and ranking, though it phrases the purpose as a question rather than 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?

Usage is implied: an agent would call this to inspect data-maintenance health. However, there is no explicit guidance on when to use it versus alternatives, no prerequisites, and no note about whether it is intended for monitoring, debugging, or pre-operation checks.

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

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

Annotations already establish this as a safe read operation, and the description adds substantial context beyond them: verbose mode is roughly 10x larger, status filtering changes which category states are included, and ranking_status/under_review_count semantics are explained.

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

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

The description is front-loaded with the core purpose and keeps every sentence relevant. It is dense and heavily parenthetical, which slightly reduces readability, but the detail is justified for a tool exposing many return 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?

There is no output schema, but the description covers the meaningful return fields, ranking statuses, verbose expansion, and status filtering. It gives an agent enough information to call the tool correctly and interpret the key results.

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

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

Schema coverage is only 50%, but the description fully clarifies both parameters. It explains that verbose adds definitions, excludes, counts, and URLs, and it explains the status enum including active, draft, archived, and all.

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: listing every ranked category, with concrete returned fields. It also distinguishes this tool from get_category by explaining that the returned slug feeds into get_category.

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

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

It gives clear usage context: default behavior is active only, while status=all includes drafts and archived categories. It also implies a discover-then-fetch workflow with get_category, though it does not explicitly compare against search or find_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?

Adds substantial behavior beyond the readOnly/idempotent annotations: append-only history, newest-first ordering, seq semantics, late-event safety, exact since behavior for events versus rounded-day summary windows, and default/max window rules. Nothing contradicts the annotations.

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

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

Purpose is front-loaded, but the rest is one dense run-on paragraph with tangled parentheticals such as 'which since can (not with since, cursor or summary)'. The information is mostly necessary, but bulleted mode structure would materially improve scanability.

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

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

Given 7 optional parameters, three modes, and no output schema, it covers mode constraints and summary/polling outputs well. Raw event object fields and list filtering behavior outside summary mode remain only partially specified.

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%, but the description still adds operational meaning: the after_id polling contract with next_after_id and start at 0, seq ordering guarantees, summary window rounding/default/max, and the default category count with lists_total. This is well beyond the field-level schema text.

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: append-only change history, with event kinds enumerated and ordering described. It also separates raw events, after_id polling, and summary digest modes, so an agent can understand the tool's scope without opening the schema. No sibling tool covers history, so differentiation is implicit but clear.

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

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

Explicitly routes between modes: use after_id instead for polling, summary=true instead for a digest, pass list for one category, and respect 'not with since, cursor or summary' incompatibilities. It also gives defaults such as the 15 busiest categories and a 7-day summary window. Sibling comparison is not needed because none of the named siblings overlaps with history.

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

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

Annotations already declare this as a safe, read-only, idempotent search. The description adds useful behavioral detail beyond annotations: it describes the returned fields (id, title, URL) and the partial-match hint behavior when not every query word matches a category.

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 two dense but front-loaded sentences with no filler. The id-to-fetch guidance and matching caveat are both relevant and placed where an agent can act on them.

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

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

For a one-parameter read-only search with no output schema, the description explains return fields and a notable edge case. It does not mention result limits, ordering, or pagination, but those gaps are relatively minor for this tool.

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

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

Schema description coverage is 100%, so the query parameter is already documented with examples. The description adds matching context by saying it uses the same matching as search_apps and explains word-level partial matching, but it does not add syntax or constraints beyond the schema.

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

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

The description states a specific verb and resource: 'Search categories and apps.' It distinguishes the scope from search_apps by noting it covers categories as well as apps, but it does not explicitly contrast with other lookup siblings like list_categories or get_category.

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 downstream usage by explaining that returned ids should be passed to fetch, including the list:<slug> and app:<slug> formats. It does not explicitly say when to prefer search_apps or other alternatives, so it falls short of full when/when-not routing.

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

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

Beyond the read-only annotations, it discloses meaningful search behavior: matching is word by word, filler words are ignored, and partial matches return categories with a hint when no result matches every word. It also states that results are summaries with compact apps, which helps set expectations for the response.

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 compact and front-loaded: it states what is searched, how matching works, what comes back, and what to do next. The examples are dense but each sentence carries useful selection or interpretation guidance.

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

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

Given the annotations, 100% schema coverage, and no output schema, the description is nearly complete for correct invocation. It explains the return shape at a high level and the fallback behavior, but it does not describe result ordering or the exact structure of the compact app summaries.

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 adds useful query semantics beyond the schema by explaining filler-word handling, word-by-word matching, and the 'apps like calm' category-ranking interpretation, though it does not add meaning for limit or made_for_iphone_duo beyond the schema.

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

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

The description gives a specific verb and resource set: find categories by name or definition and apps by name. It distinguishes the search result from deeper retrieval by naming get_category and get_app as follow-ups, so the agent can tell it apart from sibling lookup tools.

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 implies when to use search: broad or word-by-word app/category discovery, with examples like 'best free ai companion' and 'apps like calm'. It also names get_category and get_app as follow-up tools, though it does not explicitly exclude or compare against siblings such as list_categories or find_alternatives.

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