search_edition

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description usefully adds the 90-day eligibility rule and the archive_expired failure mode, but says nothing about pagination, result volume, or how the search behaves across large editions.

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 tight sentences with the eligibility constraint and the failure mode front-loaded, no filler. Minor ambiguity in 'rolling 90 Eastern calendar dates' keeps it from a 5.

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 read-only search, the description covers scope and the expired-edition outcome, which is the essential gating information. But against a 4-parameter schema with a deeply nested filter object at 0% documented coverage and no output schema, it omits filter meaning, pagination behavior, and result shape.

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 0% across 4 parameters, including a large nested filters object, and the description adds no meaning for edition_id, limit, cursor, or any filter field. With low coverage the description should compensate; instead an agent must guess filter semantics (cargo, fleet min/max, states, census_status) from bare property names.

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 ('Search the ... edition') and scopes it to the latest edition or a previously unlocked edition within a rolling 90-day Eastern calendar window. It is clear what the call does, but it never names its closest siblings (get_latest_edition, list_editions, unlock_edition), so the agent must infer the boundary.

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?

Provides an eligibility rule (must be latest or already unlocked, within 90 Eastern calendar dates) and one negative outcome ('Expired editions return archive_expired'), which implies when not to call it. It does not say which alternative to use for expired or locked editions, leaving the routing to unlock_edition/get_latest_edition unstated.

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