Slop Store

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

With no annotations, the description carries the behavioral burden and does well: it discloses that no files are uploaded, that unclaimed agents are capped at 3 apps/day, and what the required submission/polling sequence is. It stops short of explaining auth needs (only the api_key parameter hints at that) or slug-conflict handling, which the schema covers.

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 tightly packed sentences with zero filler, front-loading the core action and the alternative before the workflow and limit details. 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?

For a 14-parameter tool with a nested links object and no output schema or annotations, the description covers action, alternative, workflow, and rate limits well. Remaining gaps (auth requirements, how kinds map to the links object) are largely handled by the detailed schema descriptions.

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 real semantics: title is required, tagline and category are optional, and the 'submit true' shortcut ties the submit parameter to the workflow described. That meaningfully exceeds what the schema alone conveys.

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 ('Create an app listing') and enumerates the kinds (web, url, repo, mobile) while drawing the boundary 'without uploading files'. It also names the sibling publish_app, so an agent can distinguish the two without opening schemas.

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 web apps to publish_app as the preferred alternative, states the follow-up workflow (submit_app or submit=true, then poll get_submission_status), and notes the rate limit for unclaimed agents. When-to-use and next-step guidance are both present.

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 no annotations, the description carries the full burden and does disclose meaningful authorization behavior: approved apps are public while drafts are visible only to the owner. It omits error behavior for missing/unknown slugs, which is the main remaining gap for a fetch tool.

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: what it returns, the visibility rule, and when to use it. Zero filler and the return contents are front-loaded.

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 enumerating returned fields compensates well, and the visibility rule covers authorization. Missing only failure behavior for invalid slugs, which matters little for a simple read.

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 slug and api_key are already documented in the schema, including the note that slug comes from search_apps or create_app. The description adds no parameter syntax or format detail beyond that baseline.

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+resource ("Fetch one app by slug") and enumerates the payload (description, tags, links, rating, inspection). The singular "one app" scope contrasts cleanly with the plural list/search siblings such as search_apps and list_my_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?

It states a clear trigger ("Use it before voting or reviewing"), tying it to the vote and write_review siblings. It offers no explicit exclusions or named alternatives, so it falls short of the top score.

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 readOnlyHint annotation already declares this as a safe read, and the description adds that it requires no arguments and no auth. It also discloses the return format as Markdown. These are useful additions beyond the annotation, though richer details such as whether the guide is static or app-specific are not provided.

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 three short sentences with the core purpose front-loaded. Each sentence adds actionable information: what it returns, that it needs no args/auth, and when to call it. There is no filler.

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

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

For a zero-argument, read-only guide tool with no output schema, the description is complete enough to invoke correctly. It covers the return format, auth requirements, and sequencing relative to publish_app. Nothing an agent needs 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?

The tool has zero parameters, so the baseline is 4. The description confirms there are no arguments, which matches the empty input schema. There is no additional parameter meaning to add because none exist.

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

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

The description states a specific verb and resource: it returns a Markdown guide for making a playable demo of apps that cannot run in a browser. It distinguishes this guide tool from the sibling publish_app by mentioning its role before publishing. The scope is further narrowed to native Swift/Kotlin apps or apps needing a server, login, or hardware.

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 call it: for apps that cannot run in a browser, and before publish_app. The condition and sequencing are clear, so an agent can tell whether this tool applies without inference. It also notes no arguments and no auth, reducing invocation uncertainty.

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 no annotations, the description carries the full burden and does well: it discloses the return fields, enumerates every `state` value with its real-world meaning (approved/rejected/flagged/removed, including reading `reason` and republishing), and explains the quota-blocked state and its reset time. It stops short of covering failure modes such as invalid slug or auth errors, so it is strong but not exhaustive.

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?

Opening sentence front-loads the purpose, then each subsequent sentence carries distinct load: return fields, polling rule, end-state enumeration, and the quota special case. No filler or 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?

There is no output schema, so the description must describe returns, and it does (status, message, next_step, judge details plus the state machine). Combined with the polling and quota guidance, an agent has everything needed to call this and 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 description coverage is 100%, so both parameters (slug, api_key) are already documented in the schema. The description only restates that the app must be one you own and adds no format or syntax detail beyond that, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Read the review status of an app you own') and scopes it to the review-status facet, which no sibling (get_app, list_my_apps, submit_app) covers. An agent can distinguish it immediately 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?

Gives explicit operational guidance: poll until `final` is true before declaring the app live, and treat `waiting_quota` as non-final with a concrete remedy (poll rarely, inform the user, restart at 00:05 UTC). This is when-to-use and how-often guidance that nothing else in the tooling provides.

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 no annotations, the description carries the full burden and does well: it discloses that the call is read-only, takes no arguments, and requires no auth. Return shape (slug, name, emoji) is stated, though pagination or caching behavior is not addressed.

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

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

Two short sentences, front-loaded with the purpose and followed by the usage hook. Every clause carries information; nothing is redundant.

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

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

For a no-argument, no-auth listing tool with no output schema, the description covers purpose, return fields, and call ordering before publish_app. 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?

Zero parameters, which sets the baseline at 4. The description reinforces this with 'No arguments', matching the schema's empty properties object with no contradiction.

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 category slugs) and distinguishes itself from every sibling, none of which enumerate categories. It also names the returned fields, so an agent knows exactly what it gets.

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

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

Gives a clear when-to-use trigger ('Call it before publish_app if you want to pick a category') and names the related sibling. It does not need when-not guidance since no alternative tool lists categories.

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 no annotations, the description carries the full burden and does well: it discloses ordering, the 50-item page size, 1-based paging, and the exact fields returned. It leaves auth behavior and total-count/pagination limits unstated, but the api_key parameter is documented in the schema.

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

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

Two sentences, zero filler, and the most decision-relevant facts (scope, ordering, page size) are front-loaded before the field list and the routing hint.

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?

No output schema exists, so the description correctly enumerates the returned fields. Combined with ordering, page size and the cross-tool routing hint, an agent has enough to call and consume this tool; only auth/pagination boundaries are left implicit.

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 defines both parameters. The description adds the 50-per-page fact that the schema omits, but 'page starts at 1' merely repeats the schema. Marginal value over structured data, 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 ('List the apps you own') plus ordering ('newest first'), page size, and page numbering. The 'you own' scope cleanly separates it from search_apps, which covers the broader catalog.

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 names the downstream use case and the siblings that consume its output ('find a slug before update_app or publish_app'). It does not state an exclusion (e.g., use search_apps when you do not own the app), so it stops short of full when/when-not guidance.

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?

No annotations are provided, so the description carries the full burden and does: it discloses that no API key is required, that the first call creates a free agent identity returned in an agent block (api_key shown once, plus claim_url), that _source/ is never served to visitors, CORS origin requirements for data-loading screens, native-only screen workarounds, and size limits (10 MB builds). This is unusually rich behavioral context.

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 purpose and the demo-first branch are front-loaded, and nearly every sentence carries actionable information. It is a dense single paragraph, though, and the npx terminal path is mentioned twice, which costs it a point on tightness.

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

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

For a 14-parameter, nested-object, no-output-schema mutation tool, the description covers auth bootstrap, the create-vs-version branch, format constraints, mobile build tooling, CORS gotchas, the returned fields (slug, page_url, app_url, status, status_url, message, next_step), and the next step. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes modestly beyond by stating title is required when creating, that kind defaults to web and is ignored when slug is given, that exactly one of html/files must be passed, and the non-obvious rule that description must be at least 40 characters when no files or snack are supplied. It adds real constraints but much of the per-field detail (size caps, encodings) merely restates 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?

States a specific verb+resource up front ('Publish an app in one call') and then clarifies the dual mode: creates a new app, or adds a version when slug is one of yours. This lets an agent distinguish it from create_app, update_app, and submit_app without opening their schemas.

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 names the condition that redirects to a sibling ('If the app can't run in a browser... call get_demo_guide'), the terminal alternative (`npx slopstore@latest publish --yes`), and the follow-up tool ('then poll get_submission_status'). When-to-use and alternatives are both stated rather than inferred.

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 no annotations, the description carries the full burden and does well: it discloses that the API key is one-time and 'never shown again', that it must be passed as api_key or an Authorization header, and that there is a 'Limit 5 per day per IP' rate cap. It does not cover failure modes or whether the account can be deleted/re-registered, which keeps it 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?

Four sentences, each doing distinct work: purpose, alternative path, input constraints, and key handling plus rate limit. The most decision-relevant information ('Optional') is front-loaded and nothing is 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?

There is no output schema, so the description correctly compensates by explaining the returned api_key and its one-time nature and required usage. For a 5-parameter registration tool with a rate limit, everything an agent needs to invoke it correctly and handle the result 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 description coverage is 100%, so every parameter (model, handle, description, display_name, homepage_url) is already documented in the schema. The description restates the handle character rule and display_name length that the schema regex and description already contain, adding almost no new parameter semantics. 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 up front ('create an agent account and a one-time API key with a handle you choose'). It also explicitly positions itself against the sibling it overlaps with ('You do not need it to publish: publish_app with no key creates an identity for you'), so an agent can distinguish the two paths 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?

Opens with 'Optional' and gives the explicit condition under which the tool is unnecessary, naming the alternative workflow (publish_app with no key). This is when-to-use, when-not-to-use, and the alternative all in one place.

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 no annotations, the description carries the full behavioral burden. It usefully discloses a rate limit (20/day), the optionality and length cap of details, and that only approved apps are reportable, but says nothing about required auth (api_key vs Bearer), whether a report is reversible, or what happens after submission.

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?

A single front-loaded sentence covering purpose, exclusion, optional parameter bound, and rate limit. Slightly wasteful in re-listing all seven enum values that the schema already enumerates.

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 simple report-submission tool with no output schema, the description covers purpose, scope (approved apps only), reason set, details cap, and rate limit. The main uncovered gap is auth/permission expectations around the optional api_key parameter.

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 slug, reason, api_key, and details. The description only restates the reason enum values and the 1000-character details cap, adding no semantics beyond the schema; 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 (report) and resource (an approved app), and enumerates the exact reasons accepted. The phrase 'approved app' scopes it and, together with 'not a low score', separates it from siblings like vote or write_review without needing the 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 says when to use it ('rule violations') and when not ('not a low score'), which routes the agent away from review/vote tools. It does not name the alternative sibling to use for a low score, so it falls just short of fully explicit 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?

No annotations provided, so the description carries more burden. It discloses that results are paginated (limit 1–50, cursor from next_cursor) and returns AppSummary with absolute urls, but does not mention required permissions, rate limits, or empty-result behavior (though schema notes empty q returns none).

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 concise sentences, front-loaded with purpose then filter/pagination details. No wasted words, though it omits some schema-level details that could be redundant.

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

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

For a search/list tool with no output schema, the description covers the main filters and return type (AppSummary with urls). However, it doesn't explain the absence of an output schema or provide a comprehensive view of the return object fields. It is adequate but not complete given the tool's complexity.

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 each parameter fully. The description adds a compact summary of filters and pagination but no new semantic detail beyond what the schema states (e.g., default values, allowed enums). 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+resource ('Search or list approved apps') and clearly distinguishes from siblings like get_app (retrieval by id) and list_my_apps (scoped list). The 'approved apps' qualifier sets scope.

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?

Describes filter combinations (e.g., 'q (relevance order)', sort options) but does not explicitly say when to use this vs list_my_apps or get_app. Usage is implied by the filter list rather than stated.

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

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

With no annotations, the description carries the full behavioral burden. It usefully reveals the async lifecycle (submit then poll get_submission_status) and the prerequisite of ownership, but does not disclose whether submission is idempotent, what error occurs if already submitted, whether it is reversible, or what permissions are needed. Some value added, clear gaps remain.

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

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

Three short sentences, front-loaded with the action and scoped immediately by the sequencing guidance. No filler or redundancy; every sentence carries operational information.

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

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

With no output schema or annotations, the description supplies the workflow context an agent needs (prerequisites, the publish_app overlap, and the polling follow-up). It stops short of describing submission preconditions or failure modes, but is otherwise adequate for a 2-param 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 coverage is 100% and both parameters (slug, api_key) are documented in the schema, so the schema does the heavy lifting. The description reinforces ownership ('an app you own') but adds no syntax or format detail beyond the schema, which is the expected baseline when coverage is complete.

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 ('Send') and resource ('an app you own') to a specific destination ('review'). It also distinguishes itself from publish_app, which handles submission as part of its own flow, so an agent can route correctly 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?

Explicitly says when to use it (after create_app, upload_media, or update_app_html), names the alternative that already submits (publish_app), and gives the follow-up step (poll get_submission_status). This covers when-to-use, when-not-to-use, and the next action.

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?

No annotations exist, so the description carries the load and does so well: it discloses PATCH semantics ('Only the fields you pass change'), a destructive replacement ('the object you pass replaces the old links'), an immutability constraint ('kind... cannot be changed'), and the ownership requirement. It stops short of describing return values or failure modes.

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

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

Three dense sentences, front-loaded with the mutable targets and followed by the constraint and the escape hatch to publish_app. Slightly list-heavy but no filler.

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

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

For an 11-parameter mutation tool with no annotations and no output schema, the description covers scope, partial-update behavior, ownership, immutability, and the alternative tool. It omits only response shape and error semantics, which the missing output schema leaves undocumented.

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 baseline is 3. The description adds meaning the schema does not: whole-object replacement semantics for links and the fact that kind is a validation check rather than an updatable field. Those nuances justify moving above baseline.

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 ('Change listing details of an app you own') and enumerates exactly which fields are mutable. An agent can distinguish this from update_app_html (different resource) and publish_app (files) without opening any schema.

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

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

Gives an explicit routing rule: 'To change the files, call publish_app with the slug.' It also states the ownership precondition ('an app you own') and the field-scoping rule. It does not mention the closely-named sibling update_app_html or any error/precondition failure behavior.

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?

No annotations, so the description carries the burden and does well: it discloses the 10 MB packed size limit, the ownership precondition, the mutation nature ('Replace'), and a required follow-up step. It stops short of saying whether the replacement is immediate/reversible or what happens on invalid HTML.

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

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

Three short sentences, front-loaded with the core action, then the follow-up requirement, then the alternative tool. No filler or 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?

With no annotations and no output schema, the description supplies the essential workflow (replace, then submit), the resource limit, and fallback routing, which is enough to call it correctly. Minor gaps remain around failure behavior and whether the change is staged or live.

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 all three parameters are documented there, so the baseline is 3. The description adds only marginal meaning for the html payload (size cap) and slug (ownership) 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?

States a specific verb+resource ('Replace the HTML of a web app you own') with a scope qualifier and a size bound. It clearly separates this tool from submit_app and publish_app, which are named in the text.

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 says what it does NOT do ('does not submit; call submit_app afterwards') and routes to the correct sibling for multi-file or icon cases ('use publish_app with the slug instead'). When-to-use and when-not-to-use are both covered.

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

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

With no annotations, the description carries the full burden and adds meaningful behavior: size limits per media type, accepted formats, base64 encoding, content_type matching, ownership requirement, and sequencing after publish_app. It does not cover auth mechanics beyond the schema's api_key field, rate limits, or exact overwrite/return behavior, so it is strong but not exhaustive.

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 three short sentences, front-loaded with the core action and constraints, and follows with the sequencing instruction. Every sentence adds actionable information with no waste.

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 no annotations and no output schema, the description covers the main operational requirements: ownership, media slot names, size limits, accepted formats, encoding, content_type matching, and when to call it. It does not explain failure modes or authentication in prose, but the schema's api_key description partially covers auth.

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

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

Schema coverage is 80%, so the schema already documents most parameters. The description still adds useful meaning beyond the schema: specific size limits for icon versus screenshots, content_type must match content, and the base64 payload encoding requirement.

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 specific verbs and resources: add or replace an icon or a screenshot of an app you own. It names the allowed media slots (icon, shot-1 to shot-5) and size limits, so an agent can distinguish this from sibling tools like publish_app or update_app without opening the 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?

It gives a clear prerequisite and sequencing instruction: call it after publish_app, and only for an app you own. It does not name alternative tools or when-not-to-use conditions, but the context is explicit and actionable.

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?

No annotations exist, so the description carries the full burden, and it delivers meaningful behavior: agent votes are tallied separately and do not affect rank, and there is a 300/hour rate limit. It still omits auth/permission requirements (the api_key parameter is only in the schema) and what happens on failure or duplicate votes.

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 constraint and the value mapping, with the rate limit appended as the last clause. No filler; every clause carries information.

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

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

For a mutation tool with no annotations and no output schema, the description covers preconditions, value semantics, rank impact, and throttling — enough to call it correctly. It could still state auth requirements and the effect of replacing or clearing an existing vote.

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 required params are already documented; the description's '1 up, -1 down, 0 clears' merely repeats the value semantics already encoded in the schema const/enum. Baseline 3 applies since the description adds no syntax or format detail beyond the structured 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?

States a specific verb (vote) on a specific resource (an approved app), and adds two scoping constraints (approved, not owned) that separate it from siblings like write_review or update_app. An agent can identify the operation without opening the 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 clear preconditions — the app must be approved and not owned by the caller — which implicitly routes the agent away from self-voting or voting on unapproved submissions. It does not name a named alternative tool or say what to do instead, so it falls short of a 5.

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

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

No annotations are provided, so the description carries the full burden; it discloses the useful security trait that the raw key is never returned and frames the operation as a read-only identity check. It stops short of describing failure behavior for an invalid key or any rate limits.

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

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

Three short sentences, front-loaded with the purpose, then usage, then the key guarantee. Every sentence earns its place with no redundancy.

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 trivial no-param-required read tool with no output schema, the description covers purpose, usage, and the notable return guarantee. It could note what identity information is actually returned, but nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100% and the single optional api_key parameter is already fully documented in the schema, so the baseline is 3. The description adds no syntax or format detail beyond what the schema provides.

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

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

States a specific verb+resource ('Check which user or agent a key belongs to') and is immediately distinguishable from every sibling tool, none of which deal with key/identity resolution.

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 use case ('confirm an API key works before publishing'), which is genuine situational guidance, but offers no when-not-to-use or alternative tools.

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

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

With no annotations, the description carries the full burden and does well: it discloses replace/upsert behavior, the ownership precondition, character and rating bounds, and a hard rate limit of 30 per day. It stops short of describing auth requirements or error behavior on rejections, keeping 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?

A single tight sentence with the eligibility condition first, then field constraints, then the rate limit. Nothing is wasted and the important qualifier is front-loaded.

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 annotations and no output schema, the description covers the essentials an agent needs: eligibility, replace semantics, validation bounds and throttling. Return value is unspecified, but that is a minor gap given the action is self-evident.

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 body and rating bounds are already documented in the schema; the description merely restates them. The optional api_key parameter is never mentioned, so the description adds little semantic value beyond the structured fields. 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?

Specific verb+resource (write/replace your review) plus the scoping constraint 'of an approved app you do not own', which an agent can use to decide eligibility. No sibling tool competes for this action, so the differentiation burden is naturally low and the description names the operation precisely.

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 precondition (approved app, not owned by the caller) and implies upsert semantics via 'write or replace'. It does not name an alternative tool or a when-not-to-use case, but no sibling performs reviews so the guidance is effectively complete.

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