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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral detail by describing the result payload shape - each hit names the answering Wai tool and how to call it - which matters because there is no output schema. It does not discuss result ordering, pagination beyond the limit param, or behavior on zero matches, so it stops short of full transparency.

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?

Front-loaded with the core action and scale (Search ... more than 30,000 ready questions), followed by filters, then output shape, then usage triggers - a sensible order. The domain enumerations (solar, wind, BESS, hydro, hydrogen, data centers; EU law, Yargıtay) are long but do real work by signaling coverage. It is a single dense sentence, so a reader has to parse a lot before reaching the routing guidance at the end.

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 tool with five optional parameters, no output schema and no nesting, the description supplies what an agent needs: what is searched, how to filter, what comes back, and when to prefer it over siblings. The only residual gap is result mechanics such as ordering and empty-result behavior, which are minor for a discovery endpoint.

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 100% and every parameter carries examples, so the baseline would be 3. The description nevertheless adds framing beyond the schema by naming the four ways to narrow a search - by words, category, country (ISO code) or sector - and tying them to the library's domain coverage, which clarifies how the filters combine. The country ISO-code convention is reinforced in prose as well as in 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?

States a specific verb (Search) and a specific resource (Wai's library of 30,000+ ready questions), then enumerates the covered domains and filter axes. It also distinguishes itself from siblings by explaining that each result names the Wai tool that answers it (wai_draw_site, wai_calculate, wai_official_data, wai_trails, WaiMAP). An agent can tell this is a discovery/router tool, not a computation 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?

Gives three explicit triggering conditions: the user asks what Wai can do, the user wants ideas or examples for a field or country, or the agent is unsure which Wai tool fits a request. That last clause is an effective routing rule that steers the agent here before picking a sibling. The closing instruction to answer with the returned numbers rather than a pre-call estimate further scopes correct use.

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