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

Annotations only declare readOnlyHint=true; the description adds that this is a GET-based discovery endpoint that must precede neon_search, and explains the semantics of each kind (operators for searchFields, custom numeric ids for outputFields). Auth and rate-limit behavior are still undisclosed, but meaningful context beyond the annotations is provided.

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?

Three sentences, front-loaded with the core purpose and followed by the two kind explanations and the sequencing cue. The trailing REST path note is a minor redundancy but is compact and useful for tracing behavior.

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?

No output schema exists, so the description correctly carries the burden of explaining return content for both kinds, including the custom-field numeric ids. Combined with the mandatory precondition on neon_search, an agent has everything needed to call it correctly.

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?

With 100% schema coverage, the baseline is 3, but the description genuinely enriches both parameters: it explains that kind=searchFields returns filterable fields plus their allowed operators, and kind=outputFields returns returnable columns including custom fields with numeric ids. This adds semantic depth the enum labels alone don't convey.

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 (discover) and resource (field names neon_search accepts), and differentiates itself from siblings by naming neon_search as the consumer. The two kind values are explained in terms of their distinct outputs, so an agent can distinguish this discovery tool from the actual search tool.

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?

"Call this before neon_search" is an explicit usage directive that tells the agent exactly when to reach for this tool. It does not state when the tool is unnecessary (e.g. if field names are already known), but the sequencing guidance is clear and actionable.

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