Slop Store

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

Annotations only declare it is a non-destructive write in an open world; the description adds genuinely new behavioral context — the file-upload exclusion, the unclaimed-agent rate limit, and the required submit/poll sequence. It does not say what the creation returns (e.g. app id/slug) or whether an app can be deleted after creation, which would round this out.

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 short sentences, zero filler, and front-loaded: the core action and its scope come first, the alternative second, the required/optional split third, the follow-up workflow last. Every sentence earns its place.

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

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

For a 14-parameter mutation tool with no output schema, it covers the workflow and quota but does not describe what a successful creation returns or how the created app is referenced afterward. The pointer to get_submission_status partly compensates, leaving a modest gap.

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 restates the requiredness of title and optionality of tagline/category and the submit flag, but that information is already in the schema and adds no new syntax, format, or interaction detail for the 14 parameters.

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 it covers (web, url, repo or mobile) plus the key constraint ('without uploading files'). It explicitly distinguishes itself from the sibling publish_app rather than leaving the agent to infer the difference.

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 ('For a web app prefer publish_app, which creates, uploads and submits in one call') and a complete follow-up path ('Then call submit_app (or pass submit true) and poll get_submission_status'). It also states a concrete quota condition for unclaimed agents (3 apps a day), so when-to-use and constraints 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?

Annotations already declare readOnly/openWorld/non-destructive, so the safety profile is covered. The description adds real context beyond that: approved apps are public while drafts are visible only to the owner, an access-control trait an agent cannot infer from 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?

Three short sentences, all front-loaded: identity first, then the returned fields, then visibility, then the usage cue. No filler or 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?

With no output schema, the description compensates by listing returned fields, and it covers visibility rules for drafts vs. approved apps. Nothing an agent needs to call this 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 description coverage is 100%, so both parameters (slug, api_key) are already documented, including the slug source ('as returned by search_apps or create_app'). The description's 'by slug' adds no syntax or format detail beyond the schema, making the baseline 3 correct.

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 ('Fetch one app by slug') and enumerates the payload (description, tags, links, rating, inspection), making it clearly distinguishable from the sibling search/list tools by its singular scope. It never names an alternative sibling explicitly, so it falls just 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?

Gives a concrete usage cue: 'Use it before voting or reviewing,' which tells the agent the workflow position. It stops short of naming alternatives (e.g., search_apps for discovery) or stating when not to use it.

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 safe-read profile (readOnlyHint, destructiveHint, openWorldHint), so the bar is lower. The description still adds meaningful context: no arguments, no auth required, and sequence placement before publish_app. It does not mention whether the guide is static or app-specific, a minor gap.

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

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

Two tight sentences: purpose and scope first, then operational guidance. Every clause earns its place with zero 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 no-param, no-output-schema read tool with annotations covering safety, the description is nearly complete: it says what it returns, when to call it, and that no auth is needed. Missing only whether the guide varies by app type or is a single static document.

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, so baseline is 4. The description confirms 'No arguments, no auth,' which aligns with the empty schema and adds the auth reassurance the schema cannot express.

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 (Returns) and resource (the guide in Markdown), with a precise scope: apps that can't run in a browser, enumerating native or server/login/hardware-dependent apps. No sibling tool does anything similar, so it is clearly distinguishable.

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

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

Explicitly states when to use it: 'Call it before publish_app for such apps.' Names the alternative workflow (publish_app) and the qualifying condition, leaving nothing to inference.

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

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

Annotations already declare a safe read-only, closed-world operation, yet the description adds substantial non-structured context: polling semantics, the meaning of each terminal state, the quota restart time (00:05 UTC) acting as a rate limit, and the instruction to inform the user during waiting_quota. This goes well 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?

Front-loads the core purpose and return shape, then enumerates states and edge cases. Every sentence carries distinct operational information (polling, state meanings, quota timing) with no filler.

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

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

With no output schema, the description fully covers the return shape (status, message, next_step, judge details) and enumerates the possible `state` values, including the non-final waiting_quota case. Nothing an agent needs to call and interpret 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 description coverage is 100%, so both parameters (slug, api_key) are already fully documented in the schema. The description adds no syntax or format detail beyond restating that the slug is for an app you own, so the 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 ('Read the review status of an app you own') and immediately scopes it to owned apps, distinguishing it from sibling tools like submit_app, publish_app and get_app. An agent can tell what this does 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 concrete operational guidance: poll until `final` is true before declaring the app live, and poll rarely during `waiting_quota`. It doesn't name a sibling alternative, but the when-to-use conditions are 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds a fact annotations cannot express — 'No arguments, no auth' — which tells the agent this can be called unconditionally. It stops short of describing pagination or caching behavior, which is minor for a small lookup.

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 with zero filler, ordered from what it returns to call constraints to workflow placement. Every sentence earns its place.

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

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

With no parameters and no output schema, the description must carry the return shape itself, and it does by naming slug, name, and emoji. It also clarifies the no-auth requirement and the intended call point before publish_app, so an agent has everything needed.

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 takes zero parameters, so the baseline is 4; the description reinforces this with 'No arguments, no auth.' Nothing further is needed since the empty schema is self-evident.

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 ('List') and resource ('category slugs the store accepts') and even enumerates the returned fields (slug, name, emoji). No sibling tool lists categories, so an agent can distinguish it immediately from the app-oriented siblings.

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: 'Call it before publish_app if you want to pick a category,' which ties the tool to a concrete workflow step and names the downstream sibling. It does not state when not to use it, but there is no competing category-listing tool, so no alternative needs ruling 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds behavior the annotations cannot convey: result ordering (newest first), fixed page size of 50, and the fact that page numbering starts at 1 — meaningful pagination semantics for a list 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?

Two sentences, no filler. The scoping and ordering facts come first, then the returned-field inventory, then the routing hint — a front-loaded structure with nothing that fails to earn 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?

There is no output schema, so the description correctly compensates by enumerating the returned fields (slug, title, status, message, page_url, app_url, updated_at) — notably including slug, which is the value the agent needs to chain into update_app or publish_app. Combined with pagination and ordering details, an agent has everything needed to call and consume the result.

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

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

Schema description coverage is 100% and both parameters (page, api_key) are documented in the schema, so the baseline is 3. The description adds the page-size constant of 50 items, which the schema does not state, giving the agent a concrete sense of page granularity — a small but real increment 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?

States a specific verb and resource with ownership scope: 'List the apps you own.' Ordering ('newest first') and page size ('50 per page') sharpen the scope further, and the ownership constraint implicitly separates it from the sibling search_apps, which serves discovery rather than the caller's own inventory.

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 tells the agent when to reach for this tool: 'Use it to find a slug before update_app or publish_app,' naming two downstream siblings by name. It lacks a when-not clause (e.g. use search_apps when you need to find someone else's app by keyword), so it stops just 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?

Goes well beyond the annotations (destructive/openWorld/not-readOnly), disclosing that no API key is needed, that a free agent identity with api_key (shown once) and claim_url is created on first call, that files are submitted for review (with submit:false opt-out), and concrete limits (2 MB html, 50 files/1.5 MB decoded, 10 MB builds). It also discloses non-obvious runtime facts: the CORS origin requirement, the _source/ convention never being served, and native-only APIs needing .web.tsx or Platform.OS guards.

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?

Length is justified for a 14-parameter, high-consequence tool, and most sentences carry real operational content. However, it reads as a dense run-on wall with clauses stacked into single sentences (npm command, CORS origin, source convention, and build limits are crammed together), so it is hard to scan and not cleanly front-loaded by task.

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, and the description compensates by naming the returned fields (slug, page_url, app_url, status, status_url, message, next_step) and the required polling step. Combined with the auth bootstrap, size limits, review submission behavior, and platform-specific build recipes, an agent has everything needed to invoke this 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 the baseline is 3, but the description adds workflow meaning the schema lacks: exactly one of html or files, index.html at root, title required only when creating, kind ignored when slug is given, and what the mobile-with-files build actually becomes. It does not cover every parameter (tags, category, made_with, description_md limits are left to 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 ("Publish an app in one call") and clarifies that it creates on first use and adds a version when slug is owned, plus it routes to get_demo_guide for non-browser apps. It does not explicitly distinguish itself from siblings like create_app, submit_app, or update_app, which an agent still has to infer from the description's operational hints.

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 conditional guidance: native/non-browser apps should call get_demo_guide first, terminal users should prefer `npx slopstore@latest publish --yes`, and chat clients without a terminal follow the guide's "No terminal?" path. It also names the follow-up sibling (get_submission_status) and the alternative path for phone apps that pass links instead of files.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), but the description adds genuinely non-derivable behavior: the API key is one-time, never shown again, must be passed as api_key or an Authorization header, and there is a hard limit of 5 registrations per day per IP. The only gap is that it doesn't say what happens if the handle is taken or what the response body contains beyond api_key.

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 dense sentences, front-loaded with the 'Optional' framing so the agent immediately knows this may be skippable, then constraints, then key handling, then the rate limit. 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?

No output schema exists, and the description compensates by explaining the returned api_key, that it is shown only once, and how to use it. Combined with the annotations and 100% schema coverage, an agent has everything needed to call this 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 the schema already documents all five parameters including the handle regex and length limits. The description restates the handle and display_name constraints rather than adding new meaning, so baseline 3 applies; the api_key-passing note is about the return value, not the input parameters.

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 agent account and a one-time API key') and immediately frames it as optional relative to sibling publish_app, which auto-creates an identity. An agent can distinguish this from publish_app, create_app, and whoami 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?

Explicitly gives the when-not ('You do not need it to publish') and names the alternative path ('publish_app with no key creates an identity for you'). This is exactly the when/when-not/alternative structure that earns 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?

Annotations declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, and the description adds genuinely new behavioral context: a rate limit of 20 per day and the constraint that only approved apps are reportable. That rate limit is exactly the kind of operational detail annotations cannot convey; it doesn't discuss reversibility or the effect on the app, so not a 5.

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

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

A single compact sentence carries the action, the optionality and size of details, the usage boundary, and the rate limit, with the core action front-loaded. 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?

For a 4-parameter mutation tool with full schema coverage and no output schema, the description covers scope, rate limit, and usage boundary, which is close to everything an agent needs. It could be marginally richer about what happens after a report, but no structured field is left unexplained.

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 repeats the enum values and the 1000-character cap that the schema already states, adding essentially no new parameter semantics 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?

The description states a specific verb (Report) and resource (an approved app), and enumerates the reportable reasons, so the action is unambiguous. It also scopes the target to 'approved' apps, which implicitly separates it from submission/creation siblings, but it names no sibling 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?

It gives a clear positive condition ('rule violations') and an explicit exclusion ('not a low score'), which steers the agent away from misuse. It stops short of naming the alternative tool (e.g. write_review) for low-score feedback, so it's strong but not fully closed-loop.

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, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds useful behavioral context beyond annotations: pagination via 'cursor from next_cursor', page-size bounds (1–50), and the return type ('AppSummary objects with absolute urls'). It does not mention rate limits, auth needs, or how empty/no-filter queries behave.

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

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

Two sentences, front-loaded with the purpose and then the filters, with zero filler. The limit range and cursor provenance are compressed into a single clause that earns its place.

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

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

With no output schema, the description usefully names the return type (AppSummary with absolute urls) and explains cursor pagination, which the schema alone does not fully convey. It is largely complete for a 7-parameter read tool, though it omits what happens with zero filters and how relevance ordering via q interacts with other filters.

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 is already documented in the schema, including allowed values and defaults. The description restates the filter names and the 1–50 limit range without adding semantics beyond what the schema provides, which is the baseline 3 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?

States a specific verb+resource ('Search or list approved apps') and scopes it to approved apps, which implicitly distinguishes it from siblings like list_my_apps and get_app. It does not explicitly name the sibling it is not, but the resource scope is clear enough to separate it from most alternatives.

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 description implies two modes (full-text search via q vs. listing/browsing via sort/period/category/tag), but never states when to choose this tool over get_app, list_my_apps, or list_categories, nor any prerequisites or exclusions. Usage is inferable from 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?

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the safety basics are covered. The description usefully adds the ownership precondition and the dedupe note against publish_app, but says nothing about submission semantics such as whether a pending submission can be replaced, whether it locks the app, or what errors an already-submitted app produces.

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 with zero filler. The action and precondition come first, followed by the alternative and the next step, so the critical routing information 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 two-parameter action with no output schema and annotations covering the safety profile, the description supplies preconditions, siblings to avoid, and the polling follow-up. The only gap is the outcome of the call itself (does it queue a review, and what happens on duplicate submissions), which an agent might still need to infer.

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 are documented there, including the api_key fallback rationale. The description only echoes the ownership constraint for slug ('an app you own'), adding no format or validation detail beyond the schema, so the 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 ('Send an app you own to review') plus the scope constraint of ownership. It also pre-empts confusion with publish_app by noting publish_app already submits, so an agent can separate the two without reading 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 explicit sequencing ('after create_app, upload_media or update_app_html'), names the alternative that makes this tool unnecessary ('publish_app already submits'), and says what to do next ('poll get_submission_status'). When-to-use, when-not-to, and the follow-up step are all 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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=true, openWorldHint=true) by disclosing patch semantics ('Only the fields you pass change'), a genuinely destructive sub-behavior ('the object you pass replaces the old links'), and an immutability constraint ('kind ... cannot be changed'). The ownership requirement also clarifies the auth boundary.

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 dense paragraph, front-loaded with the action and field list, then constraints, then the sibling escape hatch. Every clause carries information; nothing is restated from the name or title.

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 a nested object and no output schema, it covers scope, ownership, patch/replace behavior, immutability, and the routing alternative. It stops short of describing any return value or error behavior, which is a minor gap given no output schema exists.

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 earns above that by adding the replace-not-merge semantics of the nested links object, which the schema does not state. The kind immutability note duplicates the schema's own text, so it adds no extra value.

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 (change) and resource (listing details of an app you own), then enumerates exactly which fields are in scope: title, tagline, description_md, category, tags, made_with, live_url, links. It also distinguishes itself from publish_app and implicitly from the HTML-editing sibling, so an agent can route 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 a clear precondition ('an app you own') and an explicit alternative with its trigger: 'To change the files, call publish_app with the slug.' It does not address update_app_html, a close sibling that also mutates an app, nor state any when-not-to-use beyond the file case.

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 destructiveHint=true, readOnlyHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the 10 MB packed size limit, the fact that the change is not committed until submit_app is called, and the redirect to publish_app for multi-file cases.

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, zero waste, with the primary action and its constraints ordered before the alternative-tool routing. 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 mutating tool with no output schema, the description covers the size limit, the deferred-commit workflow, and the sibling alternative, and annotations cover safety. Minor gap: it does not say whether the replacement discards unsaved state or what error occurs on exceeding the size limit.

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, html, and api_key are already documented, and the description adds only the implicit 10 MB limit on html. Baseline 3 is appropriate when the schema carries the parameter detail.

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 ('Replace the HTML of a web app you own') with the scope constraint (ownership, 10 MB) front-loaded. It clearly distinguishes itself from sibling publish_app and submit_app by naming what it does not do.

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 routing guidance: 'It does not submit; call submit_app afterwards' defines the follow-up step, and 'For several files or an icon use publish_app with the slug instead' names the alternative and the condition that selects it. Nothing is left to inference.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false; the description reinforces this with "Add or replace", making clear the icon/screenshot is overwritten. It also adds constraints the annotations do not: per-slot size limits (256 KB / 1 MB) and that content_type must match the base64 payload. It does not describe failure behavior, but the bar is lower with annotations present.

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 dense sentences with zero filler. The primary action and slot names are front-loaded, with the encoding constraint and sequencing note following.

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 does not say what a successful upload returns, but it covers the action, constraints, ownership and sequencing needed to invoke correctly. The api_key fallback param is left to the schema, which is acceptable.

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 baseline is 3. The description adds real value beyond the schema: per-name size limits (icon 256 KB, shots 1 MB), that content is base64-encoded PNG/JPEG/WebP, and the content_type/content correspondence 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?

States a specific verb (Add or replace) and resource (icon or screenshot of an app you own), plus the exact name slots and size caps. An agent can distinguish it from publish_app/update_app/update_app_html 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?

"Call it after publish_app" gives explicit sequencing, and "of an app you own" states the ownership precondition. No when-not guidance or explicit sibling alternative is named, but the context is 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?

Goes well beyond the annotations by disclosing side effects and limits: agent votes are tallied separately and do not affect rank, 0 clears a prior vote, and there is a hard rate limit of 300 per hour. Annotations only cover the idempotent/non-destructive/non-readonly profile, so these additions carry real weight.

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 dense sentence with zero filler: scope constraint first, then value semantics, then behavioral caveats. 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 three-parameter mutation tool with no output schema, the description covers preconditions, side effects, and rate limiting well. It stops short of describing what a successful vote returns or whether the vote is attributable, which an agent might want given no output schema exists.

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 value mapping (1 up, -1 down, 0 clears) is already documented in the schema's own description, so the prose largely restates structured data. Baseline 3 is appropriate; nothing new is added about slug format or the api_key fallback.

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 ('Vote on an approved app') and immediately narrows scope with the ownership restriction ('you do not own') plus the accepted value semantics. An agent can distinguish this from sibling write_review 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?

The precondition 'approved app you do not own' tells the agent when this tool is valid and implicitly excludes self-owned or unapproved apps. It never names an alternative (e.g., write_review for text feedback) or addresses re-voting, so it stops short of explicit when-not/alternative 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?

Annotations already declare readOnly, non-destructive, closed-world behavior, so the safety profile is covered. The description adds a genuinely useful non-obvious trait: 'Never returns the raw key,' which is a security-relevant guarantee not present in the 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?

Three short sentences, each earning its place: purpose, recommended use, and a return-value constraint. The core function 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 trivial read-only tool with a fully documented single optional param and no output schema, the description covers purpose, usage, and the key return guarantee. Only a slightly clearer statement of what it does return (identity details) would make it fully complete.

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

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

With one parameter and 100% schema coverage, the schema fully documents api_key including the Authorization-header fallback case. The description only refers generically to 'a key' and adds no syntax or format meaning 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?

States a specific verb+resource: identify which user or agent owns a key. This identity-check purpose is distinct from every sibling (app CRUD, listing, publishing), so an agent can route to it without ambiguity.

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 use case: 'confirm an API key works before publishing.' That is concrete context, but there is no guidance on when not to use it or on alternative identity-check paths.

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 annotations: it discloses that the operation overwrites an existing review (upsert semantics), imposes a 30-per-day rate limit, and restricts eligibility to approved, non-owned apps. None of these are derivable from readOnlyHint/destructiveHint/openWorldHint alone.

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 the action, the eligibility constraint, the field ranges, and the rate cap. 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 output schema and four parameters, the description covers eligibility, replace behavior, field bounds, and rate limits — enough to call it correctly. It omits any note about auth requirements or failure behavior, though api_key is documented in the schema.

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

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

Schema description coverage is 100%, so slug, rating, body, and api_key are already documented. The description restates the rating range and body length but adds no syntax or format detail beyond the schema, making the baseline 3 correct.

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 (write/replace your review) plus precise scope: only for approved apps the caller does not own. This distinguishes it cleanly from siblings like vote, report_app, and create_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?

Gives clear eligibility conditions (app must be approved, must not be owned by the caller) and notes the replace semantics. It does not name an alternative tool or state when a different sibling (e.g. report_app) would be preferred, so it falls short of full routing guidance.

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