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

Goes well beyond the annotations by disclosing the ordered pipeline (fetch, parse, filter, dedupe, transform, map_entity), the sandbox constraints on user code (JavaScript or Python, no network access), the failure mode (422 with field errors), and the return fields (draft id and manifest_hash). The only blemish is a mild tension between openWorldHint=true and the 'no network access' claim, which an agent could misread as applying to the whole tool rather than only the transform step; the description does not disambiguate that scope.

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?

Five short sentences, each carrying distinct information: what it does, how it runs, what it returns, how it fails, and what to do next. The core action is front-loaded and 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?

There is no output schema, and the description compensates by naming the returned draft id and manifest_hash plus the 422 error shape. Combined with the auth scope and the test-then-publish workflow, an agent has everything needed to invoke this correctly and handle the outcome.

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 the single manifest parameter already enumerates its expected keys (slug, version, title, summary, category, data_class, steps, pricing, test_inputs, owner). The description adds no constraint, format, or validation detail about the manifest itself beyond what the schema states, so the baseline of 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?

Uses a specific verb pair plus resource: 'Validate a listing manifest and save it as a draft you own.' The word 'draft' and the pipeline verbs distinguish it immediately from alterlab_listing_draft_test and alterlab_listing_publish, which are named explicitly as the next steps.

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 sequence of alternatives: create the draft here, test it with alterlab_listing_draft_test, then publish with alterlab_listing_publish. It also states a prerequisite (API key with listings:write scope), so the agent knows both when to call it and what must be true first.

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