plan_event_imagery

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

Even with destructiveHint=true, the description discloses the full behavior: the deterministic plan checks both Sentinel-1 and Sentinel-2 exactly once each, issues two catalog searches, costs 4 tokens, and returns per-search coverage/cloud/SAR-pair status. It also describes refusal behavior, screening/detection/identification capabilities, and explicitly states that a VHR recommendation does not invalidate free-catalog results—far exceeding the annotations.

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 relatively long but every sentence contributes substantive content: purpose, sensor behavior, output contents, capability context, usage guidance, precondition, and token cost. It is front-loaded with a clear summary, but the density of parenthetical details makes it slightly heavier than the most concise examples.

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?

The description is remarkably complete: it enumerates what the result carries, explains screening/detection/identification limitations, gives usage preference over search_imagery, states the refusal condition, and mentions token cost and the two-search behavior. For a tool with 3 parameters and an output schema, this fully prepares an agent to invoke it correctly.

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 100%, so the baseline is 3. The description adds meaningful context by explaining that analysis_goal (damage_assessment | flood_mapping | wildfire_assessment) drives the plan and cloud gating, and that event_id resolves to the event's authoritative footprint. It does not explicitly detail the optional event_date beyond implying a pre/post window, but the schema already covers that field.

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 ('Plan') and a clear resource ('imagery evidence for ONE event'), and explicitly distinguishes it from the sibling search_imagery tool ('instead of guessing collections one at a time'). It further specifies the exact sensors and analysis goals, making its purpose unmistakable.

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 explicitly says 'Prefer this over several search_imagery calls for the same event' and explains why (cannot miss the SAR look and cannot repeat a search). It also defines required inputs (event_id, analysis_goal) and a precondition (an event must have a resolvable footprint, otherwise refused), providing clear when-to-use guidance.

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