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

Annotations declare it is a non-read-only, non-destructive, non-idempotent, open-world operation, but the description adds genuinely non-derivable behavior: the two-phase staging model ("Nothing is added to a list until commit_import") and the privacy guarantee ("nothing is published"). It does not discuss auth requirements, rate limits, or what a re-run without an idempotency key does, 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?

Three tightly packed sentences with no filler, and the primary routing decision (url vs picks) is front-loaded immediately after the purpose statement. The parentheticals ("Curated reads every place", "up to 1,000 per call") earn their place by resolving the choice between the two paths, though the sentence grows long.

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 8-parameter mutating tool with no output schema and no annotations covering workflow, the description covers the essentials: intake paths, size limit, staging boundary, and publication status. It omits what the call returns (e.g. a staging handle or item count) that an agent would need to chain into `commit_import`, and never touches the destination-list parameters, which the schema carries instead.

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 high (88%), so the schema already documents most fields; the description nonetheless adds routing semantics the schema cannot express — which of `url` vs `picks` applies and the 1,000-item cap that drives the switch to `stage_picks`. It adds nothing about `list`, `own_list`, or `source_owner`, which is acceptable given the schema coverage, but leaves a small gap.

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 opens with a specific verb and resource ("Bring a whole list in to sort, privately") and then splits the operation into its two mutually exclusive intake paths (`url` for a Google Maps shared list, `picks` for anything read elsewhere). It names the siblings it hands off to (`stage_picks` for overflow, `commit_import` for finalization), so an agent can distinguish this tool from adjacent import tools 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?

It states exactly when to use each input path ("Pass `url` for a Google Maps list shared with 'Anyone with the link'... or `picks` you read yourself from anywhere else"), gives the boundary condition for the alternative tool ("up to 1,000 per call; send more with stage_picks"), and flags the prerequisite that nothing is committed until `commit_import`. That is explicit when-to-use, when-to-switch, and sequencing.

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