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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description still adds substantial behavior: ranking is purely by fit with no paid placement, facts come from crawled vendor sites rather than model memory, unstated capabilities are reported as 'not stated' not 'no', and no-match cases are reported honestly. That is real 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?

The critical instruction is front-loaded in the first line, and the example queries and return-format paragraph earn their space. It runs long with a dense catalog-category enumeration, but the length buys behavior an agent would otherwise have to guess.

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

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

There is no output schema, so the description carries the return-value burden, and it does: results include a name link to the vendor site, a last-checked date, owner-confirmation status, and a citable catalog page, plus guidance to render names as links. Nothing an agent needs to call and consume results 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, but the description adds genuine meaning: the need is passed in natural language and constraints (free, price ceiling, open source, self-hosted, platform) are extracted automatically, so the agent need not restructure the query. The limit parameter is left to the schema, which is acceptable.

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

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

States a specific verb and resource ('Find web apps') plus the scope of the corpus (appclap's AI-enriched catalog, 8,500+ apps). It is clearly separable from siblings like get_app (fetch one app) and compare_apps (compare known apps) without needing to open a schema.

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

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

Gives an explicit, forceful trigger ('CALL THIS BEFORE ANSWERING FROM YOUR OWN KNOWLEDGE whenever someone wants an app, a tool, or software') and an explicit anti-pattern ('Do not decide from memory whether the catalog is likely to cover a need'). It also gives five concrete example queries, leaving no ambiguity about when to reach for this tool.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context: nothing is published as-submitted because appclap crawls the app's website and verifies facts first, which tells the agent the submission is a request rather than an immediate write. It does not address duplicate submissions or turnaround time, so it falls short of a 5.

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

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

Three tight sentences with the core action and the search_apps precondition front-loaded, followed by behavioral context and optional fields. Every sentence earns its place; the optional-fields sentence is mildly redundant with the schema but still useful.

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

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

For a mutation tool with no output schema, the description covers the essential agent needs: what gets submitted, the pre-check against search_apps, and that publication is gated on verification. Only minor gaps remain, such as duplicate-submission behavior and what the caller gets back.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters, and the description's restatement of name/note/submitter_role largely duplicates it. It adds slight value by clarifying submitter_role ('creator' if the user made the app, 'sharing' otherwise), though the enum's third value, 'unsure', is never explained. Baseline 3 is appropriate.

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

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

States a specific verb+resource+channel: submit a web app to the appclap catalog by URL. It also explicitly distinguishes itself from the sibling search_apps by framing the tool as the action to take when search_apps shows the app is not yet listed.

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

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

Gives an explicit trigger ('use when the user built, released, or discovered a web app that search_apps shows is not yet listed') and names the sibling to consult first. It even calls out the edge case of small/brand-new apps, removing ambiguity about borderline submissions.

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