Search NEON field sites

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that the catalog is cached and no token is needed, which informs the agent about potential staleness and lack of authentication burden. It also mentions that include_elevation triggers one extra cached request, a behavioral nuance beyond the schema. Minor gap: no mention of rate limits or response size, but annotations carry the safety burden.

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 a single, information-dense sentence that front-loads the primary purpose and search dimensions, followed by a brief note on caching and next steps. No wasted words; every clause carries meaning.

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 12 parameters, most of which are optional and well-described in the schema (75% coverage), an output schema exists, and annotations cover safety, the description doesn't need to repeat parameter details. It adds the essential search modes and the important note about cached catalog and token-less operation. It is complete for an agent to decide whether and how to call this tool, though it could mention that output is paginated via limit/offset, but the schema already defines those defaults.

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 75%, so most parameters have descriptions in the schema. The description adds that proximity is 'nearest first' and that elevation includes UTM, which are not in the schema. It also clarifies that query can match state/domain names, complementing the schema's examples. Since coverage is high, the description's additions are a bonus, not compensation, justifying a 4 rather than 5.

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 states a specific verb ('Find') and resource ('NEON's 81 field sites') and enumerates the search dimensions: code, name, state, domain, site type, product availability, and proximity. This clearly distinguishes it from sibling tools like neon_get_site (which retrieves a single site) and neon_search_products (which searches products, not sites).

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 explicitly states that the tool searches a cached catalog and requires no token, which guides the agent on prerequisites. It also tells the agent what to do next ('Next: call neon_get_site or neon_get_availability(site=...) for a siteCode'), giving clear routing to sibling tools. This is above and beyond basic usage context.

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