satellite_compare

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

With no annotations, the description carries the burden and does well: it discloses cost ($0.013 USDC/call), p99 latency (8000ms), output composition (side-by-side JPEG with date labels plus change metrics and per-date cloud/haze/snow estimates). However it omits error/failure behavior and limits (e.g. what happens if no imagery is available for a date), so it is strong but not complete.

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 purpose and output shape, then scenarios, then params, then cost/latency. The single dense paragraph is information-rich but a bulleted or sentence-split structure for params would scan faster.

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?

No output schema and no annotations, but the description explains the returned composite image and metrics adequately, and covers defaults for optional params. Missing only edge-case behavior (no imagery, invalid place, out-of-range dates) to be fully complete.

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 50%, so the description compensates well by enumerating the accepted location modes (place, lat+lon+radius_km 5-500 default 50, or bbox), default dates (before = one year prior to after; after = yesterday), width range 64-768 default 384, and include_separate. It repeats ranges already in schema and doesn't explain the layer enum values, which keeps it below 5.

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+resource ('before/after satellite comparison of the same area on two dates') with concrete data source (NASA GIBS MODIS/VIIRS, ~250 m) and output form. An agent can distinguish it from the sibling satellite_image because this one pairs two dates and returns change metrics.

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?

Names concrete scenarios (floods, wildfires/burn scars, drought and lake levels, snow cover, deforestation, construction at regional scale) which gives clear positive usage context. It never states when NOT to use it or explicitly routes to satellite_image for single-date imagery, so exclusions are missing.

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