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

With no annotations, the description carries the full burden and does well: it warns that output passes through the conversation (context-window cost), discloses truncation of long strings, server-side filtering, and ordering. It omits auth/permission requirements and error behavior, 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?

Two sentences, zero waste, and the core capability plus its main parameters are front-loaded before the fallback-tool caveat. 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 5-parameter read tool with full schema coverage and no output schema, the description is nearly complete: paging, truncation, filtering, ordering, and the practical limitation are all covered. Remaining gaps (auth needs, item shape) are minor for a passthrough sample reader.

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 already 100%, so baseline is 3; the description adds genuine meaning beyond the schema by stating that results come in scrape order, that count items start from offset, that where is applied server-side with a concrete example ('price above 100, title containing a word'), and that max_chars truncates long string 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?

States a specific verb and resource ('Read a sample of a Scrapy Cloud job's scraped items') plus a meaningful scope qualifier ('in scrape order'). An agent can distinguish this from siblings like scrapy_cloud_get_job_item_stats or scrapy_cloud_get_collection_records 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 explicit context ('small sample') and a when-not rule: for anything beyond a small sample, use the shub CLI (shub items). This is strong routing guidance, though it points to an external CLI rather than naming the closest MCP sibling tool, and does not state prerequisites.

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