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

With no annotations, the description carries the burden of behavioral disclosure. It reveals notable traits: the response size stays constant regardless of plot count, empty results include a marked worked example, overlapping blocks are treated as multiple separate blocks, and overlaps should be read as intent. It does not mention auth or billing behavior, but the schema covers npub and the operation is a list/read.

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?

The description is compact at roughly 70 words and each sentence adds behavioral or scoping information: scope, item exclusion, empty behavior, and overlap semantics. The style is somewhat poetic and lacks a front-loaded verb phrase, but the structure is logical and avoids waste.

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?

Given the output schema exists and the sibling set includes related block/item tools, the description covers the key contextual cases: empty results, overlap semantics, and scope boundary. It is sufficient for an agent to select this tool and understand its unusual behaviors, though it leaves the undocumented dpop_token parameter to be inferred from convention.

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?

The description adds no parameter-level meaning beyond the schema. Schema description coverage is 67%, with npub and include_retired documented in the schema, but dpop_token remains undescribed. Since the tool description itself never mentions include_retired, npub, or dpop_token, it does not compensate for the undocumented parameter or add value beyond the input 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 ('the ground you have saved') and scope ('with its bounds'), and explicitly narrows the result to 'the blocks themselves and nothing else,' which separates it from block_item_list. It lacks a direct verb like 'list' and relies on the tool name for the action, but the resource and boundary are clear.

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?

The description gives an implicit routing cue: content like 'what grows on them, what you watch for, and what you have seen are their own listing,' signaling that this tool is only for blocks themselves and another sibling handles items. It also explains the empty-state behavior ('a grower who has saved nothing gets the worked example'), though it does not explicitly name the alternate sibling tool.

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