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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description goes well beyond them: it discloses the mapping/ranking pipeline, a retrieval ceiling of 120 providers, shared rate and concurrency limits across all callers, that search analytics are stored, and that program availability is not verified.

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 constraint, and nearly every sentence carries operational information. It is dense, and the internal pipeline detail (Jev mapping, PostgreSQL retrieval) is more implementation exposure than an agent strictly needs, which slightly dilutes it.

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?

An output schema exists, yet the description still names the salient return fields (selected_types, relevance scores, limitations), plus rate limits, the unverified-availability caveat, and the LOCATION_UNSUPPORTED recovery path. Nothing needed to invoke or interpret the call is 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 only 33%, so the description has to compensate. It does for two of three parameters, clarifying that query is natural-language interests mapped to activities and that region accepts a place name or a region ID with the response echoing the region actually searched. The limit parameter (default 10, max 25) is never explained in either place, leaving one gap.

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 and resource — searching enrichment provider records — and immediately scopes it to natural-language interests within a required region. It is clearly distinguishable from get_provider (single lookup), list_regions (region enumeration) and open_provider_explorer by naming the search/rank behavior.

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?

It gives an explicit routing rule for the sibling tool: 'call list_regions only after LOCATION_UNSUPPORTED'. It also states when not to rely on part of the input ('location words in the query are not used for filtering') and adds a privacy constraint ('Do not include child names or private details').

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