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

Annotations only declare readOnly=false, destructive=false, openWorld=false; the description adds real behavioral context not present there — retention windows (2 hours Free, 7 days Pro, forever Scale after the last run), row and payload ceilings (5,000 inline total, 25,000 rows / 20 MB via upload, ~4 MB per call), and the CSV header-row requirement. It does not say what happens on a name collision or whether any existing list state is affected, which for a non-destructive create is the main remaining unknown.

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?

Effectively one dense paragraph that front-loads the primary inline path before the two alternatives, with every clause carrying a limit or condition. Slight cost in readability from run-on construction and the dangling final fragment 'Free.', but almost 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 five-parameter, nested-object create tool with no output schema, the description covers all input modes, their limits, and data lifecycle — enough to invoke it correctly. The notable gap is the return value: with no output schema, an agent is not told whether it receives a list identifier needed to call add_rows or get_rows afterward.

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?

Beyond the 80% schema coverage, the description explains the interaction between parameters that the schema cannot express: columns are required for inline rows, rows are capped at 500 here but extendable to 5,000 via add_rows, upload triggers a PUT-to-URL workflow instead of inline data, and google_sheet_url requires a connected or link-shared sheet. It gives the actual upload contract (header row first, 25,000 rows, 20 MB), which is meaning well 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?

The description identifies the resource (a Hosted List) and enumerates the three distinct ingestion paths — inline columns+rows, upload URL, or google_sheet_url import — which is more informative than the bare name 'create_list'. It also distinguishes itself from add_rows by naming that sibling for incremental row additions. The opening phrase 'Hand rows to Sorzio' is colorful rather than precise, so the actual create semantics have to be inferred from the modes that follow.

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?

Clear routing between the three ingestion modes: inline rows for up to 500, upload when you need more, google_sheet_url for direct Sheet import, and 'use an upload for more' when exceeding ~4 MB per call. It also routes agents to add_rows for additional rows. There is no explicit statement of when NOT to use this tool (e.g., appending to an existing list should go straight to add_rows).

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