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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds response context (results carry the page URL with anchor, official link, checked date), which is useful with no output schema, but says nothing about ranking, match quality, or rate limits.

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 tight sentences: purpose and scope first, then illustrative queries, then return contents. The examples are short and each demonstrates a different query type, so nothing feels padded.

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 no output schema, the description covers return fields (URL with anchor, official link, checked date), plus scope and examples. It omits result ordering/ranking, which is the main remaining gap for a ranked search tool.

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 67%, below the 80% baseline, so the description must compensate. 'In one city or all of them' clarifies the omitted-city default that the schema ('Limit to one city') leaves implicit, and the query examples illustrate the free-text behavior of the required param.

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?

Specific verb (keyword search) and resource (every card, outing and FAQ on Littles Weekly), with an explicit scope (one city or all). An agent can distinguish it from get_page/list_pages/list_cities because it searches across all content rather than enumerating or fetching a single page.

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 example queries ('Santa breakfast', 'toddler time', 'free museum day', 'splash pad', a venue name) give a clear picture of when this tool applies, and 'one city or all of them' clarifies the city-scoping choice. It stops short of naming alternatives or when-not to use it (e.g. use get_page for a known URL).

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