detect_dark_vessels

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

No annotations are provided, so the description must carry the full behavioral burden. It does disclose several traits: zero-config, no credentials, public data usage, and the output categories (TRUSTED, DARK_VESSEL, SPOOF_OR_ABSENT) with oil slick alerts. However, it does not mention potential limitations (e.g., detection accuracy, processing time, error handling, or dependence on AIS availability). It also includes references to algorithm papers, which are not behavioral disclosures. Given the lack of annotations, a 3 is appropriate—it provides useful context but not a complete behavioral profile.

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 well-structured with clear sections (purpose, args, returns, references) and front-loads the core purpose in the first sentence. However, it includes a list of five academic references that are not necessary for an agent to invoke the tool correctly—these add noise. The overall length is justified by the parameter details, but the references could be pruned to improve conciseness.

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 the tool's complexity (7 parameters, no schema descriptions) and the presence of an output schema, the description covers all necessary input semantics, returns a summary of output categories, and mentions behavioral aspects like zero-config. It explains the purpose, parameters, and expected output formats. Nothing critical for calling the tool is missing—bbox format, date range syntax, AIS source options, and output choices are all specified. The output schema, not shown, likely provides the detailed return structure, so the description's return text is supplementary.

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?

With schema description coverage at 0%, the description must fully compensate, and it does. The 'Args:' section explains every parameter in plain language: bbox with coordinate order and datum, datetime_range with example, ais_source with options, pfa_factor with meaning (CFAR threshold), sea_state with options, custom_ais_records with required fields, and format with output formats. This is a textbook example of compensating for an undocumented schema.

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 a precise statement of functionality: 'Detect maritime vessels in Sentinel-1 SAR imagery and correlate them with open AIS transponder data to flag unreported ‘Dark Vessels’'. This clearly specifies the resource (SAR + AIS data) and the action (detection and correlation), and distinctly separates it from siblings like detect_water_sar (water vs vessels). It also adds the compliance context (MSFD Descriptor 8), which is a useful, specific qualifier.

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 description notes 'Zero-config: Queries public Sentinel-1 and open AIS telemetry without credentials or API keys', which implies it is for users without credentials, but it never explicitly says 'use this tool when you need to detect dark vessels' or contrasts with alternatives. No when-not or exclusion criteria are given. The usage context is only implicitly conveyed via the zero-config mention; there is no direct guidance on when this tool is more appropriate than other vessel-detection utilities.

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