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

Annotations already declare this a read-only, idempotent, closed-world search, so the description correctly spends its budget on data semantics: winterStoragePrice is a yard-confirmed 2026–27 price carrying confirmed_at and verification_event_id, or null when unconfirmed. That provenance detail is genuinely additive and tells the agent not to treat null as a missing-data error.

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 scope and the confirmed/null price rule are front-loaded, which is the right ordering. The closing sentence stacks three guide references, which is useful routing but the densest part of the definition; the whole thing remains tight with no filler.

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?

With an output schema present, the description needn't document return values, and it covers the one thing the schema cannot: the meaning of the null-vs-confirmed price field. Annotations, schema, and description together leave nothing an agent needs missing.

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 coverage is 100%, so the baseline is 3, but the description adds real meaning for the confirmed flag by defining what 'confirmed' means (yard-confirmed price with confirmed_at and verification_event_id) rather than just restating the field label. Other parameters (q, limit, region, category) are left entirely to 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?

Opens with a specific verb and resource plus geographic scope: 'Find Seacoast ME–NH and Casco Bay boatyards, marinas and storage'. The parenthetical '(public-web listings, not partners)' distinguishes it from sibling find_boating_businesses, and the singular/plural naming makes clear it is the list counterpart to get_yard.

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 routes agents elsewhere for adjacent needs: posted prices to get_seacoast_costs or the winter-storage guide, ramps and tides to two named guides. It does not explicitly state when to call get_yard instead, but the list-vs-single distinction plus the named alternatives give clear context.

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