get_nearby_events

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

Annotations already provide readOnlyHint and openWorldHint, so the description correctly extends them rather than repeating. It adds meaningful behavioral detail: data is normalized from multi-state feeds, coverage varies by state with a docs reference, later states appear automatically, and every event names its publishing agency in the source field. It does not mention pagination, rate limits, or the full event response shape, but the supplied annotations lower the burden; this is a strong, non-contradictory supplement.

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 organized into clear paragraphs: scope, data details, California vs. nationwide usage, then parameter definitions. Every sentence carries useful information, though it is somewhat longer than strictly necessary. The front-loaded purpose and explicit usage guidance make it easy to scan; minor verbosity prevents a 5.

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?

Given no output schema and zero schema description coverage, the description covers all necessary invocation details: geographic scope, data types, state coverage variability with a doc pointer, parameter formats and limits, and sibling differentiation. It does not describe the response event structure beyond the 'source' field, which is a minor gap, but the tool's purpose and invocation are fully specified.

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 0%, yet the description fully compensates by explaining each parameter: 'center is "lat,lon"', 'kinds is a comma list from: incident, closure, chain, fire, sign, rwis, camera, toll (toll adds live and fixed toll prices where agencies publish them)', and 'radius_km caps at 160.' It also clarifies the default behavior implicitly and gives valid values, which the schema alone does not provide.

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 opens with 'Live road events near a point anywhere CommuteScout covers' – a specific verb, resource, and geographic scope. It explicitly differentiates from California-centric siblings by stating 'For CALIFORNIA questions prefer the dedicated tools above' and positions this tool for outside California, near borders, or as a supplement. An agent can immediately distinguish it from sibling tools like get_incidents or get_lane_closures.

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?

Provides explicit when-to-use/when-not-to-use guidance: 'prefer the dedicated tools above' for California, and 'Use THIS tool for any location outside California, near a state border, or as a supplement when a California tool comes back empty.' It even names the alternative tool category and the condition for falling back, leaving no ambiguity about selection.

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