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

Beyond the readOnlyHint=true annotation, the description discloses rich behavioral traits: dimension coverage caveat ('other dimensions return coverage=not_captured'), pagination contract ('follow nextOffset with unchanged filters'), a hard page cap ('Max 25 results per page'), sort order ('nearest first then stable ID'), and a citation duty ('Cite canonicalUrl and sourceJsonUrl'). No contradiction with annotations.

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?

Seven sentences, each carrying distinct operational value — purpose, prerequisite, exclusions, dimension caveat, radius semantics, sorting/pagination, citation and cap. It is front-loaded with the purpose statement. Dense but not bloated; the only near-redundancy is the radius range restating a schema default range, though the schema lacks an explicit min/max so it is genuinely new information.

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 10-parameter tool with output schema present and readOnly/destructive annotations covering the safety profile, the description covers the operational contract well: prerequisite workflow, dimension caveat, pagination, page cap, and citation. Remaining gaps are hide_changed and min_y/max_y semantics, plus fallback behavior when coordinates have no resolved base — minor but non-trivial for correct invocation.

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 only 20% (dimension and block_type), so the description must compensate — and largely does: radius semantics and range ('Radius is horizontal blocks, 1..8192'), dimension behavior via the coverage caveat, limit via 'Max 25 results per page', offset via 'follow nextOffset', and block_type values in the first sentence. Residual gaps: hide_changed and min_y/max_y semantics are explained nowhere.

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?

Opens with a specific verb+resource+scope: 'Find historical NoCom chest/shulker/ender-chest block positions near native Minecraft coordinates.' The block-type specificity clearly distinguishes it from siblings like find_nocom_portals (portals) and find_locations_near (named locations), and the exclusion 'Not inventories, ownership or current survival' sharpens the boundary further.

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?

Explicitly prescribes a prerequisite workflow: 'Resolve a named base with get_location/search_locations first and use its native dimension,' and states exclusions ('Not inventories, ownership or current survival'). It stops short of naming an alternative sibling for those excluded concerns or for other block categories (portals/signs), so it lacks full when-not-alternative routing.

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