AppClap

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

Annotations already cover read-only, idempotent, non-destructive, open-world, but the description adds genuinely new behavior: facts sourced from each product's own site, unstated fields marked "not stated" rather than guessed, out-of-catalog apps excluded and named, and per-app links that resolve to the vendor's site. That is meaningful disclosure beyond the structured hints.

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

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

Front-loaded with the comparison scope and dimensions, then usage, then grounding caveats and link-presentation guidance. Three short paragraphs, each doing work, though the closing link instruction is slightly verbose for what it conveys.

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

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

With no output schema, the description carries the return-shape burden and does: results contain per-app links on names, unstated fields appear as "not stated", and excluded apps are named. An agent has everything needed to call and present 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 description coverage is 100%, so both parameters (names, focus) are already documented, including the 2-5 bounds and focus examples. The description restates the 2-5 constraint and echoes the same focus examples, adding no new semantics over the schema.

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

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

Specific verb (compare) plus resource (apps), with explicit scope (2-5, side by side) and the exact dimensions compared (pricing, free tier/trial/OSS/self-hosting, shared vs unique features). It is clearly distinguishable from get_app and search_apps, which fetch or find rather than compare.

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

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

Gives a clear triggering condition ("when the user weighs specific apps against each other") with concrete examples ("Notion vs Coda", "which of these is cheapest") and notes that out-of-catalog apps are excluded and named. It stops short of explicitly routing the agent to search_apps to discover or validate app names 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 already cover safety (readOnlyHint, idempotentHint, destructiveHint=false) and openness, so the bar is lower, yet the description adds real behavioral context: every field is sourced from the vendor's own website, unstated fields are reported as 'not stated' rather than guessed or defaulted. That convention materially changes how an agent should interpret a returned record.

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

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

Front-loaded with the returned fields, then provenance, then the link-presentation rule — each block earns its place and there is no filler. Slightly verbose in the final paragraph about links, which is presentation guidance rather than tool behavior.

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

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

With no output schema, the description carries the burden of describing return values and does so thoroughly, including provenance and the link field. The remaining gap is failure behavior: what happens when the name matches nothing or matches multiple apps is never stated.

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

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

Only one parameter and schema coverage is 100%, so the schema already documents the 'name' string with an example ('Netlify'). The description adds no extra semantics such as whether the name must match exactly or how ambiguous/partial names are handled, 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 ('Get the full grounded record for one app by name') and enumerates exactly what comes back: description, category, pricing, features, platforms, open-source status. The singular 'one app by name' scopes it clearly against the plural sibling search_apps and compare_apps.

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

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

Usage is implied rather than stated: the singular, full-record framing suggests lookup-by-known-name rather than discovery or comparison, and the 'do not infer that an unstated capability is absent' line guides interpretation of results. However, no sibling is named and there is no explicit when-not-to-use or prerequisite (e.g. use search_apps first if the exact name is unknown).

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. Beyond that, the description adds genuinely useful behavioral context: the report is 'a signal, not an edit,' never directly changes data, and triggers re-verification against the app's website. It does not describe acknowledgment/response behavior or rate limits, and there is mild tension between readOnlyHint=false and 'never directly changes data,' though the latter refers to app records rather than the report itself.

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

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

Front-loaded with the core purpose and the catalog constraint, and every sentence carries routing or behavioral information. The second sentence is long and packs multiple clauses, but no sentence is wasted.

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

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

For a three-parameter, no-output-schema tool, the description covers the action, the required enum values, the non-edit semantics, and the sibling routing condition. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the description reinforces the allowed reason enum values and clarifies that name must be a listed/cataloged app. It adds modest semantic flavor (what each reason category means at a high level) but does not go beyond the schema on details formatting.

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 (report) and resource (app issue) and precisely scopes it to apps that are already in the appclap catalog, with concrete examples of issue types. It explicitly distinguishes itself from the sibling submit_app by naming the out-of-catalog case.

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 the trigger condition (wrong, outdated, or missing details on a cataloged app) and the explicit exclusion plus alternative: 'For apps NOT in the catalog, use submit_app instead.' An agent can route correctly without 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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered; the description instead spends its words on behaviour the annotations cannot express: ranking is by fit with no paid placement, facts come from vendor-site crawls, unstated capabilities are reported as 'not stated' rather than 'no', and empty results are returned honestly. It also discloses the per-result metadata (last-checked date, owner confirmation, citable catalog page), which is exactly the operational context 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?

The highest-value directive is front-loaded in a single bolded-feeling sentence before any catalog detail, so an agent can act on the first line alone. It is nonetheless a long definition, and the closing paragraph's instruction about presenting links restates the same point twice ('Results carry a link on each app's name' then 'Present them as links rather than plain names').

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

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

There is no output schema, so the description must carry the return-value burden, and it does: ordering semantics, result metadata, citation source, null-result behaviour, and how to render links. For a two-parameter read-only search tool, nothing an agent needs in order to call it correctly or interpret the 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 would be 3, but the description genuinely adds interpretation the schema lacks: constraints embedded in the phrasing (free, price ceilings, open source, self-hosted, platform) are 'extracted and applied automatically; there is no need to restructure the request', reinforced with five worked examples. The `limit` parameter is left entirely to the schema, which keeps this just 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?

Opens with a specific verb and resource ('Find web apps') plus the catalog it searches ('appclap's AI-enriched app records'), then bounds the scope explicitly ('Covers web-based apps'). An agent can distinguish this from sibling tools like get_app or compare_apps 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, emphatic when-to-use rule ('CALL THIS BEFORE ANSWERING FROM YOUR OWN KNOWLEDGE whenever someone wants an app, a tool, or software') and closes the escape hatch by pre-empting the alternative ('Do not decide from memory whether the catalog is likely to cover a need'). The cost argument ('this search is cheap') and the domain list make the trigger condition unambiguous.

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

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

Goes well beyond the annotations by explaining that nothing is published as-submitted and that appclap crawls and verifies the site, plus what the reply contains (claim instructions for creators). It does not state rate limits, duplicate-submission behavior, or whether a failed crawl is reported back, which keeps 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?

The core action and trigger come first, then optional fields and the email/claim instructions. It is on the long side and the email guidance is restated twice ('pass it on', 'pass it only if they give it'), which costs a bit of tightness but no sentence is filler.

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

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

With no output schema, the description carries the return-value burden and does so: it says what the reply contains (how to claim the listing, notification when live). For a non-idempotent, open-world submission tool, the verification behavior, optionality, and follow-up flow are all covered.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real decision guidance: only url is needed, name/note/role are optional, submitter_role means 'creator' only if the user made the app, and email must be offered and never invented. That is meaning beyond the field definitions, though it doesn't cover formats or edge cases for url.

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 (submit) and resource (a web app) and the destination catalog, with the key mechanism (by URL) front-loaded. It also names the sibling tool search_apps as the discovery counterpart, so an agent can separate submission from lookup 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?

Explicit trigger: use when the user built, released, or discovered a web app that search_apps shows is not yet listed. That is a when-to-use condition plus an alternative (search first) and even a target audience (small/brand-new apps), leaving little to infer.

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