Spot card

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered and the bar is lower. The description adds only what is returned ('full card', 'spots within a radius'), with no mention of error behavior, missing-spot handling, or result limits. Modest added value against an already-covered annotation set.

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?

A single tight sentence with no filler, and the primary 'full card' case is front-loaded ahead of the secondary radius listing. It is arguably over-compressed, since 'known spot' and 'card' are never unpacked, but there is no wasted text.

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 four-parameter, all-optional tool with no output schema and thin param docs, the description leaves major questions open: what a 'card' actually contains, and what a call with no spot_id and no coordinates returns. Given every parameter is optional, the default/no-argument behavior is a real gap that only the description could fill.

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 only 25% – lat, lon and radius_km carry no descriptions at all. The phrase 'within a radius of a point' loosely ties radius_km and the coordinate pair together, but says nothing about the 30km default, the 1-200 bounds, or that spot_id and coordinates are alternative modes. It does not compensate for the coverage 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 names the resource (a spot) and two concrete retrieval modes: a full card for a known spot, or a listing of spots within a radius. An agent can infer this is a detail/lookup tool rather than a search or forecast tool. It stops short of explicitly distinguishing itself from siblings like find_spot or spot_forecast, so it is clear but not sibling-differentiated.

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 'or' construction implies two usage modes but never states which inputs select which mode, nor when to prefer this tool over find_spot or spot_forecast. The useful routing hint ('preferred over raw coordinates') lives in the schema, not the description. No exclusions or alternatives are offered.

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