Datalastic Vessel Tracking & Maritime Intelligence

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

The description discloses key behavioral traits beyond the readOnlyHint: it is an estimate rather than an observed fix, it is the heaviest call because it builds a route, and it can fail to extrapolate when the estimated_position equals the last known lat/lon. This gives the agent critical expectations about accuracy, cost, and failure semantics.

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 long but every sentence earns its place: it fronts the core purpose, then gives prioritized tool-selection guidance, and finally covers user communication and failure behavior. There is no redundant filler or repetition of the schema.

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 analytical complexity and open-world context, the description is complete: it explains staleness, computation inputs, tool ordering, output caveats, and user-presentation expectations. An output schema exists, so return-value details are not required to be repeated here.

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?

The input schema already fully documents all three parameters and the exactly-one-of mmsi/imo/uuid requirement (100% coverage). The description adds no identifier-specific semantics, so the schema carries the parameter burden and the baseline score of 3 is appropriate.

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 clearly states the tool 'estimate[s] where a vessel is right now when its last AIS position is stale,' specifying the computation inputs: last known fix, destination port, and route-based ETA. It also explicitly distinguishes this from an observed position, separating it from get_vessel and get_vessel_pro.

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 gives explicit tool-selection guidance: use get_vessel first, use get_vessel_pro for ETA/destination, and use this tool only when both the last known position is old and a destination/ETA exists. It also says to offer the estimate to the user first, making when-to-use and when-not-to-use unambiguous.

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

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

Annotations already establish readOnly, openWorld, and non-destructive behavior; the description adds a non-obvious behavioral guarantee ('Always returns a list, even for a single match') and scopes the search to the port registry. It does not cover result limits or empty-input behavior, but with annotations carrying the safety profile the added context is solid.

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?

Two sentences cover purpose, return fields, search modes, single-match list behavior, and alternative tool. Every sentence earns its place and the key purpose is front-loaded.

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 tool with nine optional parameters and no required fields, the description gives enough orientation to select search modes and know the return shape. It leaves minor ambiguity about whether multiple filters can be combined and what an empty search returns, but the output schema and 'always returns a list' guarantee cover most operational needs.

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 applies. The description does add helpful grouping of the nine parameters into search modes (name with optional fuzzy, UN/LOCODE, classification, country, geography), but it largely restates constraints already present in the schema such as radius requiring lat and lon.

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 specific verb and resource: 'Search the port registry and return matching ports' plus the exact fields returned. It also differentiates from the sibling get_port by stating that full detail on one known port belongs there.

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 usage criteria: 'Use this to discover ports or resolve a name to a UN/LOCODE/uuid' and names the alternative get_port for known-port detail. This tells an agent exactly when to pick this tool over siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds valuable behavioral context: it clarifies that results are static reference data (not live), explains pagination via next token, and mentions the credit cost. These are beyond what annotations provide, though it does not detail every edge case (e.g., idempotency), which is acceptable given the openWorldHint.

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 dense but well-organized. It front-loads the core search capability, then covers return data, pagination, credits, and alternatives. Every sentence contributes to the agent's decision-making, though it could be slightly condensed without losing information. No fluff is present.

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 (17 parameters) and the presence of an output schema, the description is complete for an agent to call it correctly. It covers what is searched, the nature of the results, pagination, cost, and when to use alternative tools. The schema handles parameter details, so nothing critical is missing.

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?

The input schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds meaning beyond the schema by imposing a logical constraint ('Provide at least one search criterion') and clarifying pagination usage (the 'next' parameter). It also summarizes the main filter categories, reinforcing the schema without redundancy.

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 clearly states the tool's purpose: searching the vessel registry by multiple criteria, and explicitly differentiates it from sibling tools by mentioning live position (get_vessel) and area-based search (get_vessels_in_radius). It uses specific verbs and resource names, leaving no ambiguity about what the tool does.

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 provides explicit when-to-use and when-not-to-use guidance. It states 'Provide at least one search criterion' (a usage constraint), mentions the credit cost, and names alternatives for live position and area searches. This leaves no doubt about when this tool is appropriate.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description does not need to restate safety. It adds value by describing the specific data returned (terminal list with name, company, coordinates, etc.) and the constraint of providing exactly one identifier. It does not contradict annotations and provides meaningful behavioral context beyond the structured hints.

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 two sentences, with the primary action and return fields front-loaded, followed by usage guidance. Every sentence earns its place with no redundancy or filler. The structure is clean and immediately scannable.

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 tool has an output schema, so return value details are already defined. The description covers purpose, return fields, lookup methods, and the alternative tool. It leaves nothing essential unexplained for an agent to correctly invoke it. The 'exactly one' constraint is explicitly stated, and the read-only nature is covered by annotations.

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% — both parameters (uuid and unlocode) have detailed descriptions including the 'exactly one' rule and format examples. The description reiterates this but does not add new information beyond what the schema already provides. The baseline of 3 is appropriate because the schema carries the full semantic load.

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 explicitly states the tool returns detailed information for a single port, enumerates the exact fields (identity, country, UN/LOCODE, classification, coordinates, maritime area, terminals), and differentiates it from sibling find_ports by specifying the lookup key (uuid or UN/LOCODE). This is a clear, specific verb+resource description that leaves no ambiguity about what the tool does.

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 explicitly states when to use this tool versus find_ports: 'To search for a port by name or location, or when you don't have an exact identifier, use find_ports first.' It also clarifies that this tool requires an exact identifier (uuid or unlocode) and that exactly one must be provided. This is strong guidance with a clear exclusion and alternative.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it returns live coordinates, speed, course, heading, navigation status, and raw AIS destination text, and it requires exactly one identifier. It also clarifies that the destination text is raw AIS text, not a recognized port, which is a meaningful behavioral nuance. It doesn't mention rate limits or error behavior, but the annotations plus the explicit identifier constraint provide solid transparency.

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 two sentences, front-loaded with the core purpose and identifier constraint, then the alternative tool routing. Every sentence earns its place: the first defines what the tool returns and how to identify the vessel, the second tells the agent when to use the sibling instead. No wasted words.

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 read-only lookup tool with a rich output schema, the description covers the purpose, identifier constraints, return contents, and the alternative for richer data. The output schema exists, so return values don't need to be spelled out. The only minor gap is error behavior (e.g., what happens if no vessel matches), but that's not essential for a read-only lookup with a clear identifier constraint.

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 100%, so the schema already documents all three parameters. The description adds value by stating the 'exactly one of' constraint and the digit counts (9 for MMSI, 7 for IMO), which reinforces the schema's examples and helps the agent pick the right identifier format. It doesn't add much beyond that, but the baseline is 3 and the description does add meaningful constraint context.

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 ('Return'), a specific resource ('current position and basic information for a single vessel'), and the exact identifier options (MMSI, IMO, UUID). It also distinguishes itself from get_vessel_pro by listing what the pro version adds (destination/origin port, ATD, ETA, draught). This is a clear, specific purpose that an agent can act on.

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 explicitly says 'This is the default tool for vessel lookups' and names the alternative (get_vessel_pro) with the exact conditions for choosing it: when you need recognized destination/origin port, ATD, reliable ETA, or draught. This is explicit when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: data availability starts 2021-08-10 and only position changes are stored, explaining why stationary periods may have gaps. This goes well beyond what annotations or schema convey.

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 two sentences, front-loads the core purpose, and packs the critical constraints (identifier selection, time range options, data availability, and data gap caveat) with no fluff. Every sentence earns its place.

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 that an output schema exists, return values do not need to be described. The description covers all necessary call semantics: identifier exclusivity, time range selection, date bounds, data availability, and the position-change storage behavior. An agent has enough context to invoke the tool 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 description coverage is 100%, so the schema already documents each parameter, including formats and the 'exactly one of' and 'days OR from/to' rules. The description reinforces these constraints but does not add meaning beyond the schema, so the baseline score of 3 is appropriate.

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 clearly states the action ('Return the historical track') and the resource ('ordered position records for a single vessel'). It further specifies the identification options (MMSI, IMO, UUID), making it easy to distinguish from sibling tools like get_vessel or estimated_vessel_position.

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 gives clear usage constraints: exactly one identifier must be provided, and the time range must be specified either via 'days' or 'from'/'to', not both. It does not explicitly name sibling alternatives or say when not to use this tool, but the context strongly implies this is for historical tracking versus current vessel data.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context by clarifying this is static reference data rather than live position, which is not captured in the annotations. It does not discuss error handling or missing-vessel behavior, but the existing annotations lower that bar.

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?

Three focused sentences: the first gives the action and identifier constraint, the second summarizes returned data, and the third handles sibling differentiation. No filler or redundant detail.

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?

With an output schema present, annotations covering safety, full schema parameter coverage, and a description that defines identifier selection and sibling routing, an agent has everything needed to invoke this tool 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 description coverage is 100%, and each parameter already describes its format and the exactly-one constraint. The description repeats this information without adding meaning beyond the schema, so baseline 3 is appropriate.

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?

States a specific verb and resource: 'Return static specifications for a single vessel'. It also explicitly distinguishes itself from siblings by saying it is 'NOT live position' and naming get_vessel and find_vessels as the appropriate alternatives.

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 routing guidance: use get_vessel for current position and find_vessels for registry searches by attributes. This directly answers when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds useful behavioral context: it is 'heavier on the backend', it returns a specific enriched set of fields, and it notes staleness handling with a pointer to an estimation tool. This goes beyond the annotations without contradicting them.

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 two sentences, but the second sentence is dense and packs a lot of information. It is still efficient and front-loaded: purpose first, then usage guidance, then the staleness alternative. No fluff, but slightly long due to the amount of necessary detail.

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?

An output schema exists, so return-value structure is already covered. The description fully addresses when to use the tool, what it returns, why it is heavier, and even suggests a fallback tool for stale positions. For a tool with this level of complexity and a well-defined niche, nothing essential is missing.

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?

The input schema has 100% description coverage, with each parameter (mmsi, imo, uuid) fully documented and the 'exactly one' constraint stated in both the schema and the description. The description reinforces the exclusivity requirement but adds no new syntactic or semantic details beyond the schema, so the baseline of 3 applies.

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 clear, specific statement: it is the 'Richer, heavier variant of get_vessel' and lists exactly what additional data it returns (destination/origin port, ATD, ETA, draught). It explicitly distinguishes itself from the sibling get_vessel, so an agent can immediately tell them apart.

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 gives explicit when-to-use guidance: 'Prefer get_vessel for ordinary position or identity lookups; use get_vessel_pro only when the user asks about the destination or origin port, departure time, arrival time or ETA, or draught.' It even names the alternative for stale positions (estimated_vessel_position), making the decision path clear.

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

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

Annotations already declare read-only, non-destructive, and open-world semantics. The description adds valuable detail beyond those annotations: only successfully found vessels are returned, the response includes a found count, and result fields match get_vessel. This tells the agent how partially matched batches are handled.

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?

Three sentences: purpose and limit, return behavior, and usage direction. Front-loaded with the core action; no filler and no repetition of schema details.

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?

With annotations covering safety and an output schema present, the description covers the essential runtime behaviors: accepted inputs, total identifier cap, partial-result handling, and the single-vessel alternative. Nothing an agent needs to decide or call correctly is missing.

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?

The schema documents each parameter with format constraints (7-digit IMO, 9-digit MMSI, UUID), but the description adds the cardinality and mixing rule — any combination of MMSI, IMO, and UUID lists with a combined cap of 100 identifiers — which is absent from the schema. This is meaningful added value.

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?

States a specific verb ('Return'), the resource ('current position and basic information for many vessels'), and the input mix ('MMSI, IMO and UUID lists, up to 100 identifiers'). It also distinguishes itself from get_vessel by naming the single-vessel alternative, so an agent can tell them apart immediately.

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?

Explicitly says to use this tool 'instead of many get_vessel calls' when looking up a known set and 'for a single vessel use get_vessel.' That clear when-to-use/when-not-to-use guidance is exactly what an agent needs to choose correctly among siblings.

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

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

Annotations already establish readOnlyHint and non-destructive behavior, and the description adds valuable behavior beyond that: radius bounds, pagination with a 'next' token for up to 500 vessels per page, exact center exclusivity, and credit charging per vessel. No contradiction exists between the description and 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 a single front-loaded paragraph that states core behavior first, then center modes, filters, pagination, and cost. Every sentence contributes essential decision or invocation information without filler.

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 14-parameter tool, the description covers center exclusivity, radius constraints, filtering options, pagination behavior, and resource cost, while an output schema covers the response shape. No critical gaps remain for selection or invocation.

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?

All 14 parameters are described in the schema, so the baseline is 3. The description adds cross-parameter meaning not present in the schema, especially the requirement to specify the center in exactly one way and the pagination loop using the 'next' response token.

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 specific verb and resource: 'Scan a circular area and return all vessels currently within a given radius.' This clearly identifies the tool as a radius-based area scan and distinguishes it from single-vessel retrieval siblings such as get_vessel or get_vessel_info.

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 gives clear context by framing the tool as an area scan with center alternatives (coordinates, port, or vessel) and optional filters. It does not explicitly name alternatives or provide when-not-to-use guidance, so it stops short of a 5.

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

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

Annotations already establish read-only, non-destructive behavior, and the description adds meaningful context beyond them: vessel-based lookups use the last known position, current conditions are the default mode, and each returned weather field has a matching entry in a *_units object. This helps the agent interpret and use results without contradicting 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 four tightly packed sentences: output scope first, then location resolution, then mode selection, then units. Every sentence carries operational information, and there is no filler or repetition of the schema.

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 an output schema exists and all parameters have schema descriptions, the tool description sufficiently covers location disambiguation, default mode, alternative forecast modes, and output unit behavior. An agent has everything needed to select and invoke the tool 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?

The schema already documents all 8 parameters, so the baseline is 3. The description adds value above the schema by imposing the 'exactly one of' cross-parameter constraint and by explaining the units-object relationship, which is not derivable from individual parameter descriptions.

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 specific verb and resource ('Return weather for one location') and enumerates the marine and atmospheric fields returned, so an agent knows exactly what the tool does. The scope ('one location') also separates it from vessel, port, and history tools among siblings.

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 clearly instructs how to specify a location ('exactly one of: coordinates ... a vessel ... or a port') and how to choose current, daily, hourly, or combined modes. It provides strong context but does not explicitly enumerate when not to use this tool versus sibling tools, though sibling names make that largely unnecessary.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe read-only nature is established. The description adds useful context such as the record contents and the Maritime Reports add-on membership, but it does not go further to describe pagination, absence behavior, or data freshness. This is acceptable given the annotation coverage, but the value added is modest.

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 compact, front-loaded with the core action, and contains no filler. Every sentence contributes either to purpose, use-case, or invocation parameters, while the add-on note adds useful context without bloating the 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 read-only lookup tool with an output schema, fully documented parameters, and clear annotations, the description is nearly complete. It covers what the tool returns, why it might be used, and how to invoke it. A minor gap is the lack of precedence guidance when both imo and name are provided, but this does not seriously undermine usability.

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 100%, so the parameters are already well documented in the schema. The description restates the identification approach (imo or name, from/to period) and reinforces the relationship between parameters, but it does not add meaningful details beyond what the schema already provides. A baseline score of 3 is appropriate.

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 uses a specific verb ('Retrieve') with a clear resource ('vessel's recorded maritime incidents'), and enriches it with event categories like groundings, collisions, fires, and detentions. It also states what each record contains (date, category, narrative), making the tool's purpose unmistakable and distinct from sibling tools like intel_inspections or intel_drydock.

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 gives clear context for when to use the tool ('risk and condition assessment') and how to identify the vessel (imo or name) with an optional date range. It does not explicitly name alternatives or exclusion conditions, but the purpose and scope are clear enough to guide selection among siblings.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the description does not need to restate safety. It adds only the add-on context and fuzzy-matching behavior, but does not disclose rate limits, authentication requirements, or behavior when no matching vessel is found.

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 two sentences with the core return value front-loaded and no filler. The field list is long but purposeful; the add-on clause is contextual rather than essential, so it is not perfectly tight.

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 100% parameter coverage, output schema, and read-only annotations, the description covers the essential return set and identifier/filter modes. It leaves minor ambiguity about whether at least one identifier or filter is required, but the schema and description together are adequate for an agent to invoke the tool 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 description coverage is 100%, so the baseline is 3. The description adds useful grouping by identify-versus-filter modes, but most parameter meaning is already present in the schema and the description does not explain updated_from or company IMO filters beyond those schema descriptions.

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 a specific verb and resource: return a vessel's classification society plus a detailed list of technical particulars, owner/manager, and survey dates. The long but explicit field list makes it easy to distinguish from sibling tools such as intel_engine or get_vessel_info.

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 gives useful targeting guidance (identify by IMO/name, use fuzzy for loose matching, or filter by owner/manager) and notes the Maritime Reports add-on. However, it does not name any sibling alternatives or state when to prefer this tool over comparable intel_* or get_vessel tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description complements them by explaining that company_imo is the company's own IMO rather than a vessel IMO, which is a meaningful behavioral nuance. It also lists the profile fields returned, going beyond the annotation safety 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 front-loaded with the core purpose, then covers returned fields, search methods, the critical company-vs-vessel distinction, and the alternative tool in three concise sentences. Every sentence earns its place with no fluff or repetition.

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 rich annotations, complete 100% schema coverage, and an existing output schema, the description provides all the context an agent needs to select and invoke the tool correctly. It covers purpose, parameters, scope, and the key disambiguation from intel_ownership.

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 100%, so the parameters are fully documented in the schema. The description reinforces the company_imo distinction, but this information already appears in the schema's parameter notes, so the description adds limited additional semantic value beyond the structured data.

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 and resource ('Look up a maritime company profile') and enumerates the returned fields. It also distinguishes itself from intel_ownership by clarifying this is a company directory, not a vessel lookup, making sibling differentiation explicit.

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 explicitly tells the agent when to use this tool ('Search by the company's own IMO number or by name') and when not to: 'to find the companies behind a specific ship use intel_ownership.' This provides clear context and a named alternative, leaving no ambiguity about the intended use case.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: it can target a single vessel OR scan a forward window across the fleet, and it returns planned and past dates plus contact details. It doesn't mention pagination or output limits, but the output schema exists and the read-only nature is well covered.

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?

Three sentences with no filler. The core purpose is front-loaded, the two usage modes are clearly separated, and the add-on note is a single useful qualifier. Every sentence earns its place.

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 read-only lookup tool with a full output schema and 100% parameter coverage, the description is nearly complete. It explains the two invocation modes and the data returned. The only minor gap is that it doesn't state whether the date-range scan requires at least one of dry_dock_from/dry_dock_to, but the schema's optional parameters and the description's phrasing make this a small omission.

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 100%, so the schema already documents all four parameters. The description adds the relationship between dry_dock_from/dry_dock_to as a forward-window scan, which is useful, but it doesn't add format details beyond what the schema provides. Baseline 3 is appropriate.

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 a specific verb ('look up') and resource ('dry-dock dates, special-survey dates, IOPP certificate dates, technical manager contact details'), and distinguishes two usage modes: single-vessel lookup by imo/name and fleet-wide date-range scan. This clearly differentiates it from sibling tools like intel_inspections or intel_class, which cover different maritime data domains.

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 explicitly states when to use the tool: to look up dry-dock/survey/IOPP dates and technical manager contacts, and when to use the date-range parameters to scan the fleet. It also notes it is part of the Maritime Reports add-on, which signals a prerequisite/availability context. It doesn't explicitly name alternatives, but the domain-specific scope is clear enough to route an agent correctly.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=false, and destructiveHint=false, so no safety contradictions. Description adds useful context: it returns specific engine fields, allows fuzzy matching, and notes it's part of an add-on, which helps the agent understand scope and potential access limitations. This goes beyond 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 concise (about three sentences) and front-loads the core purpose and output fields. It efficiently conveys identification methods and the add-on note without fluff. Every sentence contributes value.

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 moderate complexity, an output schema exists, and annotations cover safety, the description is mostly complete. It specifies output fields and identification methods. It could benefit from noting that no parameters are required, but that's inferrable. Minor gap, so 4 is suitable.

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 covers all 4 parameters with descriptions. The description adds no extra semantics beyond what's in the schema, but the schema is quite complete. Baseline 3 is appropriate given 100% coverage.

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?

Description clearly states 'Return the main-engine specification for a vessel' and enumerates the specific fields (designation, builder, propulsion, MCO). It distinguishes itself from siblings like intel_class and intel_info by focusing on engine specs, and mentions the add-on context, ensuring clear differentiation.

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?

Description implies usage: 'Identify the vessel by imo or name' and mentions fuzzy matching, but it doesn't explicitly state when to use this tool over other intel tools or exclude alternatives. It provides minimal guidance on choice between imo vs name. Could be improved by noting typical use cases, but it's adequate.

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

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

Annotations already declare readOnlyHint=true, so the description doesn't need to repeat that. It adds value by enumerating the specific data categories the add-on unlocks, which helps the agent understand what information the tool can reveal about the account's capabilities. This is behavioral context beyond the annotations, though it doesn't describe the tool's own side effects or response format.

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 a single long sentence starting with the core action, followed by a list of offerings and then usage triggers. It's slightly verbose but each element is functional: the list informs the agent of possible query scope, and the triggers clarify invocation. No filler sentences.

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 has no parameters and an output schema is present, the description covers all necessary aspects: what the tool does, when to use it, and what the add-on includes. The agent can confidently invoke it without missing context, and the output schema will handle return structure.

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?

The tool has zero parameters, so there is nothing to explain. A baseline of 4 is appropriate because the description correctly omits parameter details, and with 100% schema coverage and no params, there's no gap to fill.

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 uses a specific verb 'Check whether' and a clear resource 'Maritime Reports add-on', and states exactly what the tool confirms. It distinguishes itself from siblings by focusing on add-on status rather than data retrieval, which is implicit in the naming but made explicit by mentioning 'intel_*' tools.

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 provides explicit trigger conditions: when the user asks about add-on availability, when an intel_* tool indicates it's missing, or after a purchase/update. This is precise guidance that tells the agent exactly when to invoke this tool, and it even implicitly excludes other scenarios.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds context about the data fields returned and the add-on, but does not disclose any special behaviors like rate limits, pagination, or identifier requirements beyond what is implicit. It does not contradict 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 two sentences, front-loaded with the primary purpose and returned data, then parameter usage. There is no wasted language, and it is easy to scan quickly.

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 output schema exists, the description need not explain return values. It covers the purpose, key parameters, and the add-on context. The only minor gap is that it does not explicitly state that at least one of imo/name is required, though this is strongly implied. Overall, an agent has enough to call 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?

The schema covers all four parameters with descriptions, so the baseline is 3. The description adds relational meaning by stating 'Identify the vessel by imo or name' and 'optionally bound the period with from / to', clarifying that imo and name are alternative identifiers and that from/to are optional bounds. This adds value beyond the schema's individual descriptions.

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 clearly states the tool retrieves a vessel's Port State Control inspection record and enumerates the specific data fields returned (authority, port, type, date, detention, deficiencies). It is specific about the resource and action, and the phrase 'Part of the Maritime Reports add-on' helps distinguish it from the many other intel_* siblings.

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 implies when to use it by specifying what it returns (PSC inspection data), which differentiates it from sibling tools like intel_class or intel_drydock. However, it does not explicitly state exclusions or compare with alternatives, relying on the content to signal applicability.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Beyond that, the description adds useful behavioral context: what fields are returned, that company queries return every vessel under that company, and that it is part of the Maritime Reports add-on. No contradiction with 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?

Three focused sentences with no filler. The primary outcome is front-loaded, the two lookup modes are clearly separated, and the add-on note is brief but relevant.

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 covers purpose, output fields, and query modes, and an output schema exists. However, it does not state whether the seven optional parameters are mutually exclusive or can be combined, which is a meaningful gap for a tool with multiple query modes. Pagination or result limits for company-wide queries are also not mentioned.

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 schema already documents each parameter. The description adds value by grouping parameters into two semantic modes (vessel lookup vs company reverse-lookup) and clarifying what company-name parameters return. It does not add new format details, but supplements the schema meaningfully.

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 a specific verb and resource: reveal the commercial control behind a vessel, listing beneficial owner, operator, technical manager, commercial manager, P&I club, and flag. This clearly distinguishes it from sibling tools like get_vessel_info or intel_companies by focusing on the ownership/management chain.

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 gives explicit usage patterns: look up by imo or name, or reverse-lookup by company name to list controlled vessels. It clearly explains when each parameter mode is appropriate, though it does not explicitly compare against alternatives such as get_vessel or intel_companies.

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

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

Annotations only indicate non-read-only status. The description adds critical async behavior (returns report_id and _PENDING_), idempotency warnings (do not resubmit), failure handling (report _FAILED_ to user), queue limits (10 pending), and the server never downloading. This richly discloses behavioral traits beyond 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 long but information-dense, with each sentence earning its place: purpose, alternative, async contract, retry warnings, queue limit, and note that the server never downloads. It is front-loaded with the core purpose then flows into critical operational details; slightly verbose but justified by tool complexity.

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 complex async job submission tool, the description covers the full lifecycle: submission, polling via report_status, result_url handoff, failure handling, queue constraints, and scope (whole dataset vs single vessel). With an output schema present, no return-value details are needed, and nothing critical is missing.

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?

Input schema already has 100% coverage for the single report_type parameter, including the full dataset list. The description repeats the list but adds no semantic detail about individual datasets, meeting the baseline for full schema coverage.

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 action ('Submit an async job to export a FULL bulk dataset') with the exact resource (Maritime Reports add-on datasets) and explicitly contrasts single-vessel lookups. While it doesn't differentiate from the sibling report_request, the add-on qualifier and dataset list make the tool's role unambiguous.

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 guidance: points to lookup tools (intel_ownership, intel_inspections) for single vessels, and gives detailed workflow instructions (submit once, poll report_status, handle failures, avoid resubmission due to queue limits). This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that this is part of the Maritime Reports add-on, which is useful context about availability. It does not disclose details like whether the data is delayed, whether both imo and name can be combined, or what happens if no transactions are found, but the annotations carry the main behavioral burden.

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?

Three sentences with no filler. The core purpose and data fields are front-loaded, followed by use case, identification method, and add-on note. Every sentence earns its place.

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 tool has an output schema, so return values are already documented. The description covers purpose, use case, identification, and optional date bounds. It could mention that no parameters are required (all optional) or clarify behavior when both imo and name are omitted, but overall it is complete enough for an agent to call 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 description coverage is 100%, so the schema already documents all four parameters. The description adds the relationship between imo and name ('use when the IMO is unknown') and the from/to bounding concept, but it does not add much beyond what the schema already says. Baseline 3 is appropriate.

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 ('Retrieve') and resource ('ship sale-and-purchase transactions for a vessel'), and enumerates the exact transaction types and data fields (seller, buyer, reported price, price per lightweight ton, demolition destination). It clearly distinguishes itself from sibling tools like intel_ownership or intel_drydock by focusing on sale/purchase and demolition records.

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 says it is 'Useful for asset valuation and market tracking,' which gives clear context for when to use it. It also explains how to identify the vessel (by imo or name) and optionally bound the period with from/to. It does not explicitly name alternative tools or state when not to use it, but the context is clear enough among the siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds value by stating 'Listing is free and never re-runs a report,' clarifying side-effect behavior. It also discloses response contents (result_url on DONE, message on FAILED), which is useful beyond the bare 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 three sentences with no filler: purpose and response shape, use cases, and a side-effect guarantee. The main verb is front-loaded and every sentence earns its place.

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 zero-parameter tool with a provided output schema and safety annotations, the description covers purpose, usage scenarios, response fields, and the no-re-run guarantee. Nothing needed to invoke it correctly is missing.

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?

The tool takes zero parameters, so there are no parameter semantics to document. Per the baseline for a no-parameter tool, this is adequate.

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 specific verb and object: 'List the caller's recent async report jobs with their statuses.' It further details what is returned for DONE vs FAILED reports, making the tool's purpose unmistakable and distinguishing it from siblings like report_status and report_request by framing it as an overview/recovery tool.

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 explicitly states when to use it: 'Use this to recover a report_id, see which reports have finished, or find out why one failed,' with a concrete example. However, it does not name alternative tools or provide when-not-to-use guidance, so it stops short of full decision-tree routing.

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

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

Annotations are minimal (readOnlyHint=false, openWorldHint=true, etc.), but the description richly discloses behavior: async execution, immediate return of report_id and _PENDING_ status, polling requirement, failure handling, account limit of 10 pending reports, and that the server never downloads files. It also notes credit consumption for some report types. No contradiction with 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?

Though long, every sentence earns its place. The description front-loads the critical async behavior, then systematically covers report types and parameters, then credit notes. No redundant or filler content; structure is logical and scannable.

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 complexity (6 params, multiple report types, async behavior, credit implications), the description is fully complete. It covers return behavior, polling, failure handling, limits, and user communication. The presence of an output schema covers return format, and the description complements it well.

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% (all params have descriptions), but the description adds substantial per-report-type semantics: which parameters are required/optional, constraints (radius <=50 NM, date ranges), and default behavior (request_usage defaults to last month). This goes well beyond the 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?

States a specific action ('Submit an async report job') and resource ('async report'), and distinguishes itself from intel_report_request and report_status. The description also enumerates the supported report types, making its scope unambiguous.

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 guidance on when to use: submit once, poll with report_status, don't resubmit while running, handle failures by reporting to user, and account limits. It also directs users to intel_report_request for add-on bulk datasets, giving clear alternatives.

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

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

Annotations provide readOnlyHint=true and destructiveHint=false, but the description adds critical behavioral details: time-limited links requiring a fresh call, the server never downloading the file, terminal FAILED status, automatic retries, and cost implications. These are beyond the annotations and essential for correct agent behavior.

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 long but every sentence earns its place, explaining statuses and required actions. It is front-loaded with the core purpose and then layers behavioral nuances logically. There is no fluff or repetition.

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 output schema exists (implied by statuses and fields), the description covers all necessary edge cases: polling behavior, expiry, failure handling, cost transparency. An agent has everything needed to invoke and respond correctly without additional context.

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% for the single parameter, and the description essentially repeats the schema's meaning ('from report_request or report_list'). Since the schema already documents the parameter well, the description adds minimal new semantic value. Baseline 3 is appropriate.

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 clearly states the tool's function: 'Check an async report job by report_id' and enumerates the possible statuses. It names the resource (report) and the action (check), and distinguishes itself from siblings by referencing report_request and report_list as sources of the report_id.

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 guidance: 'by report_id (from report_request or report_list)'. It also gives detailed instructions for each status outcome—when to wait, when to hand off a result, when to relay a failure message—and explicitly forbids resubmitting without user consent. This far exceeds typical usage guidance.

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

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

Annotations already carry readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context beyond that: the output is schematic, not navigable, and it enumerates exactly what it ignores (actual navigation, hazards, traffic separation, drafts, local rules). This is critical misuse-prevention context for a tool whose results could otherwise be mistaken for real navigation guidance.

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 front-loaded with action and result, then parameter modes, then the caution, then use cases — a sensible order where the most decision-relevant facts come first. The cautionary section is longer than typical but earns its length because misuse (real-world sailing) carries genuine risk. 'Part of the Maritime Reports add-on' adds minor context without bloating the 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?

With an output schema present, full parameter coverage, and safety-carrying annotations, the description covers the two things an agent most needs: which parameter mode to use per endpoint, and the route's non-navigable nature. The one gap is behavior when called with no parameters at all — with 0 required params, a sentence on the default/error behavior would make it 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 100%, so the baseline is 3; the description adds meaning beyond the individual parameter docs by specifying the alternation/grouping semantics: each endpoint (origin/destination) may be supplied as coordinates, a port UUID, or a port UN/LOCODE. This clarifies valid parameter combinations and the mode-per-endpoint decision, which the flat 8-parameter schema alone does not convey.

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 opening sentence names a specific verb ('Calculate') and resource ('schematic sea route between two points'), then pins down the output format (GeoJSON LineString of waypoints) and metrics (kilometres and nautical miles). The 'SCHEMATIC' qualifier and distinct geospatial output clearly distinguish it from siblings in the list (get_weather, find_ports, estimated_vessel_position), so an agent can tell this tool apart without inspecting the schema.

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 states explicit intended uses ('estimating distance and travel time, visualizing the approximate path/shape, and similar analysis') and an explicit when-not ('do NOT use it for real-world sailing') with concrete reasons (no hazards, traffic separation, drafts, local rules). It does not name an alternative sibling tool, but none of the listed siblings appears to offer navigable routing, so the exclusion stands on its own.

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