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.