Datalastic Vessel Tracking & Maritime Intelligence

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

Discloses it's an estimate, not observed; explains calculation method; notes it's the heaviest call; advises presenting results as estimate and handling case where estimated_position equals last known lat/lon.

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?

Well-structured and front-loaded with key information, but slightly verbose. Each sentence adds value, though some could be condensed without loss.

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 no annotations and an output schema, the description is comprehensive: covers usage, behavior, result interpretation, and user guidance. No gaps remain.

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% with clear descriptions. Description adds no extra parameter details beyond schema, but does not need to. 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 it estimates a vessel's current position when AIS is stale. It distinguishes from siblings like get_vessel and get_vessel_pro, specifying conditions for use.

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 guides to use this tool last, only when prior lookups show old position and vessel has destination/ETA. Also advises offering estimate to user and clarifying when extrapolation fails.

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?

With no annotations provided, the description carries full responsibility for behavioral transparency. It accurately says the tool returns a list even for a single match, and lists output fields. However, it could mention potential limitations like max results or pagination, and does not cover auth or rate limits, but for a search tool this is acceptable.

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 long, front-loaded with the purpose, and every word adds value. No redundancy.

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 (9 optional params, 0 required) and presence of an output schema (though not shown), the description adequately explains the tool's input capabilities and output behavior. It covers different search modes and return shape. A 5 would require mentioning output schema details or pagination limits.

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 baseline is 3. The description adds value by explaining the meaning of parameters in context (e.g., 'optionally fuzzy', 'max 50 nautical miles' for radius, and grouping parameters logically for geographic or name searches).

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 starts with a clear action verb 'Search' and specifies the resource 'port registry' and returned fields. It explicitly distinguishes the tool from the sibling 'get_port' by stating its use for discovery and name resolution, while the sibling is for full details on a known port.

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 ('discover ports or resolve a name to a UN/LOCODE/uuid') and when not ('for full detail on one known port... use get_port'). This provides clear guidance on tool selection.

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?

No annotations provided, so description carries full burden. It discloses that returns are static reference data (not live), paginates up to 500 per page, and requires at least one criterion. Does not mention auth or rate limits, but given the tool's nature, these are less critical. Slight omission of order or empty result handling, but overall high 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 a single paragraph but front-loads the core purpose, then lists alternatives and constraints. Every sentence serves a purpose: what it does, what it returns, how to use, and when to choose alternatives. 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?

Given the output schema exists (not shown but indicated), the description doesn't need to detail return format, but it already mentions the fields returned. It covers pagination, required criteria, sibling differentiation, and credit cost. For a tool with 17 params and no required ones, the description is 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 baseline 3. The description adds value by noting that fuzzy matching only works with name, and that no MMSI/IMO is needed. However, most parameters are already described in the schema, so the description does not add substantial new meaning beyond grouping and 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 starts with 'Search the vessel registry by any combination of...' clearly stating the verb (search) and resource (vessel registry). It lists specific search criteria and distinguishes from sibling tools by contrasting static registry data vs. live position (get_vessel) and area-based search (get_vessels_in_radius).

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 states 'Provide at least one search criterion' as a requirement, explains pagination with the next token, and gives direct alternatives: 'For a vessel's live position use get_vessel; for vessels currently in an area use get_vessels_in_radius.' Also notes credit cost (1 per vessel found).

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?

No annotations provided, so description carries full burden. It discloses the lookup method and return structure. Though it does not explicitly state read-only or other behavioral traits, the nature of a get operation is implied and sufficient for a simple lookup tool.

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 well-structured sentences: returns listed, lookup method, alternative tool reference. No redundancy, front-loaded with purpose.

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?

Despite output schema existence, description lists return elements, covers lookup parameters, and directs to sibling for broader searches. Complete for a simple get-tool with two parameters.

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%, but description adds value by clarifying the mutual exclusivity of uuid and unlocode, specifying format (5 alphanumeric characters, case-insensitive), and providing an example (ESMPG).

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 verb 'Return' and resource 'detailed information for a single port', enumerates what is included (identity, country, UN/LOCODE, etc.), and distinguishes lookup by exact identifiers, differentiating it from sibling find_ports.

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 instructs to use find_ports when searching by name or location, or when lacking an exact identifier, providing clear 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?

With no annotations, the description fully discloses returned fields (coordinates, speed, course, heading, navigation status, raw AIS destination) and identifier constraints. Could mention data freshness (real-time vs. cached) but still strong.

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 concise sentences with no filler. Front-loaded key info (what it returns) followed by identification rules and alternative tool guidance. 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 the complexity (3 params, output schema present), the description covers all necessary context: what data is returned, how to identify the vessel, and when to use a more feature-rich sibling. No gaps.

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 baseline is 3. The description adds value by clarifying that exactly one identifier must be provided and lists the three options (MMSI, IMO, UUID) with usage 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?

Clearly states the tool returns current position and basic info for a single vessel, identified by MMSI, IMO, or UUID. Distinguishes from sibling tool get_vessel_pro by specifying what get_vessel does not provide (destination, ATD, ETA, draught).

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 provides when to use this tool ('default tool for vessel lookups') and when to use an alternative ('For the recognized destination...use get_vessel_pro'). This helps the agent decide between 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?

Discloses that only position changes are stored (stationary periods may have gaps) and data available since 2021-08-10. Without annotations, this provides good behavioral context, though safe/read-only nature is implied but not stated.

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, front-loaded with purpose, then parameters and constraints. No redundancy, each sentence adds 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?

Covers identification, time range methods, constraints, data availability, and storage behavior. Output schema exists, so return format not needed. Distinguishes from siblings adequately.

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%, but description adds extra meaning: clarifies identifier formats (9-digit MMSI, 7-digit IMO), time range options with mutual exclusivity, and the 'to' constraint. Adds data availability date.

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 it returns historical track (ordered position records) for a single vessel, with specific identifiers. Distinguishes from sibling tools like get_vessel or find_vessels.

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?

Explains when to use (historical track) and how to specify vessel and time range. Provides constraints (e.g., 'to' at most 30 days after 'from'), but lacks explicit exclusions or alternatives to this tool.

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?

Although no annotations are provided, the description transparently sets expectations by labeling the data as static reference data and listing included fields. It lacks minor details like authentication requirements or data freshness, but is still clear.

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: first states purpose and identification method, second lists contents and usage guidance. No unnecessary words; all information is relevant and efficiently presented.

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 presence of an output schema, the description does not need to detail return values. It covers the tool's purpose, identification requirements, data contents, and distinction from similar tools, providing everything the agent 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?

The input schema already provides full coverage and descriptions for each parameter. The description adds value by summarizing that exactly one of the three IDs must be provided, reinforcing the exclusivity constraint not fully captured in 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 clearly states the tool returns static specifications for a single vessel, using one of three identifiers. It distinguishes from siblings like get_vessel (live position) and find_vessels (registry search).

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 tells the agent when to use this tool ('reference data, NOT live position') and provides alternatives: 'use get_vessel for the current position, or find_vessels to search the registry by attributes.'

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?

With no annotations, the description carries the full burden. It states it is 'heavier on the backend', describes the extra fields returned, and hints at staleness handling. Could mention more about error cases or rate limits, but overall provides good 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?

Single paragraph is informative and well-structured, no wasted words. Could be slightly more concise, but effective.

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 complexity, presence of output schema, and high parameter coverage, the description is complete. It even advises on alternative tool (estimated_vessel_position) for stale positions, showing awareness of the broader 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% and description adds context: 'exactly one of', format hints (9 digits, 7 digits), and purpose. Goes beyond the schema by clarifying mutual exclusivity and providing examples.

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 it is a richer variant of get_vessel for a single vessel, listing additional data fields (destination port, origin port, ATD, ETA, draught) and specifying identification by exactly one of MMSI, IMO, or UUID. It distinguishes itself from sibling get_vessel by naming it as the heavier variant.

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 'Prefer get_vessel for ordinary position or identity lookups; use get_vessel_pro only when...' and lists specific conditions (destination/origin port, departure time, ETA, draught). Also mentions when to consider estimated_vessel_position if stale.

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?

With no annotations, the description must disclose behavioral traits. It states that only successfully found vessels are returned and that the response includes a count. It also mentions that each result has the same fields as get_vessel. However, it does not disclose error handling, rate limits, or behavior when identifiers are invalid. This is adequate but not fully detailed.

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, each sentence adding distinct value: purpose and parameters, return behavior, and usage guidance. No fluff or redundancy. Front-loaded with the core action and resource.

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 of a bulk lookup tool and the existence of an output schema (though not provided), the description is sufficiently complete. It mentions the count of found vessels and the field equivalence to get_vessel. It could be improved by clarifying that missing identifiers are silently ignored, but overall it provides enough context for an agent to use 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 coverage is 100%, so the baseline is 3. The description adds value by specifying that identifiers can be mixed (any combination of MMSI, IMO, UUID) and that the total is capped at 100. It also explains that each result mirrors get_vessel fields, which goes beyond the 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 clearly states 'Return the current position and basic information for many vessels in a single call' and specifies the identifier types (MMSI, IMO, UUID) and the limit of 100 identifiers. It explicitly distinguishes from siblings by advising 'for a single vessel use get_vessel'.

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 guidance: 'Use this instead of many get_vessel calls when looking up a known set of vessels; for a single vessel use get_vessel.' This clearly indicates when to use and when not to use. However, it does not mention alternatives among other sibling tools (e.g., get_vessel_pro, get_vessel_history), but the context is sufficient.

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?

Without annotations, the description fully discloses behavior: pagination (500 per page, 'next' token), credits per vessel, and that it returns distances. No contradictions.

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, front-loaded, and uses clear enumeration. Every sentence adds necessary context without redundancy.

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 (14 parameters) and presence of an output schema, the description covers all essential aspects: usage, pagination, credits, and optional filters. It is sufficiently 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%, but description adds value by explaining radius constraints, center specification (exactly one way), and optional filters. It also clarifies pagination and credit charging.

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 scans a circular area and returns vessels within a radius, specifying the center options and optional filters. It distinguishes well from sibling tools like get_vessel or find_vessels.

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 explains when to use the tool (area scan) and how to specify the center, but does not explicitly state when not to use or mention alternative tools. However, the sibling tool list provides context.

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?

With no annotations provided, the description carries the full burden. It discloses that each weather field has a corresponding '_units' object in the response, and that location must be specified as exactly one of the given methods (mutual exclusivity implied). It does not mention authentication or rate limits, but as a read-only weather tool, this is acceptable.

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 at 4-5 sentences, with the main purpose stated first. Every sentence adds necessary information: what the tool returns, how to specify location, mode options, and the presence of units objects. No unnecessary words or redundancy.

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 8 parameters, no required params, and an output schema, the description covers all key aspects: location specification (with multiple identifier types), mode selection, and a hint about the response structure (units objects). It does not need to explain output schema details since that is provided separately.

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, so each parameter is already documented. The description adds value by grouping location parameters and explaining the mutual exclusivity condition ("exactly one of"). It also explains the mode parameter values and the combination option, which goes beyond the schema's item description.

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 it returns marine weather for one location, listing specific data fields (wave height, swell, SST, etc.). It distinguishes itself from sibling tools like find_vessels or get_port, which focus on vessel/port data, not weather. The verb 'return' and resource 'marine weather' are specific and 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?

The description provides clear instructions on how to specify the location using exactly one of coordinates, vessel identifiers, or port identifiers. It explains the mode parameter options (current, daily, hourly, combination). It does not explicitly state when not to use this tool or mention alternatives, but the guidance is sufficient for typical use.

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?

No annotations provided, so description carries full burden. It discloses that incidents have date, category, and narrative, but does not mention any behavioral traits like auth needs, rate limits, or data freshness. Adequate for a simple read operation but minimal detail.

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 with no wasted words; front-loaded with action and key details, then specifics. Efficient and well-structured.

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 simplicity (4 optional params, output schema exists), the description covers the incident types, data fields, and usage context. It mentions the add-on. Could be slightly more explicit about return format but output schema suffices.

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 already describes all 4 parameters (100% coverage), and description adds context by clarifying that vessel can be identified by imo or name and that from/to are optional date bounds, adding value beyond 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?

Description clearly states it retrieves a vessel's recorded maritime incidents, listing specific examples (groundings, collisions, etc.) and the data fields (date, category, narrative). It distinguishes from sibling tools by being part of the Maritime Reports add-on and focusing on casualties/incidents.

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 mentions it is 'useful for risk and condition assessment' and specifies identification by imo or name with optional date bounding, but does not explicitly state when not to use or provide alternatives 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?

No annotations provided, so description must describe behavior. It discloses the returned data fields and input methods. Does not mention side effects, authentication needs, or rate limits, but for a read-only query tool this is acceptable. Lacks detail on error handling or default behavior when no IMO/name given.

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: first lists outputs concisely, second describes input methods. No wasted words, front-loaded with key information.

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 8 parameters, no required ones, and an output schema present, the description covers the main use cases. It could clarify interaction between multiple input parameters (e.g., if both imo and name are provided) and the effect of the date filter, but overall sufficient.

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 baseline is 3. The description adds value by explaining that 'fuzzy' enables loose name matching and that owner/manager parameters filter results. This goes beyond the 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?

Clearly states the tool returns a vessel's classification society and technical particulars. The verb 'Return' and specific list of outputs (gross tonnage, deadweight, etc.) make the purpose unambiguous and distinct from sibling tools like intel_info or intel_ownership.

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?

Explains how to identify vessels via IMO, name (with fuzzy matching), or filter by owner/manager. Mentions the add-on requirement. However, lacks explicit guidance on when not to use this tool or which sibling to choose instead.

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?

No annotations are provided, but the description clearly indicates a read-only lookup operation by stating 'Look up a maritime company profile' and describing returned data. It also clarifies the distinction between company IMO and vessel IMO, which is important behavioral context.

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 paragraph but is well-structured and contains all necessary information. It could benefit from slight restructuring for easier scanning, but there is no wasted content.

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 presence of an output schema and 3 parameters, the description is complete. It explains the search methods, clarifies potential confusion about IMO numbers, contrasts with a sibling tool, and lists the output fields.

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 describes parameters. The description adds valuable context by explaining that `company_imo` is the company's own IMO (not a vessel IMO) and that `updated_from` is a date filter. This goes beyond the schema's basic 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 looks up a maritime company profile and lists the returned fields (owners, operators, etc.). It distinguishes from sibling `intel_ownership` by specifying that this tool uses company IMO, not vessel IMO.

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?

Explicit when-to-use and when-not-to-use guidance is provided. It says to search by company IMO or name, and tells users to use `intel_ownership` for finding companies behind a specific ship.

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?

No annotations are provided, so the description carries full burden. It describes a read-only operation (look up, scan) and specifies the data returned (dates, manager details). It does not disclose any side effects, permissions, rate limits, or data freshness. For a read tool, this is adequate but not rich.

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?

Description is three sentences, front-loads the core purpose, and then gives the alternate usage mode. It is concise with no unnecessary words. The mention of the add-on is relevant for access context.

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 4 well-described parameters and an existing output schema, the description covers the tool's functionality adequately. It mentions what the response includes (dates, manager details) and the two usage scenarios. It is complete for a tool of moderate complexity.

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 4 parameters described). The description adds context on how to use parameters: imo/name for single vessel, dry_dock_from/to for date-range scanning. It does not add syntax or additional constraints 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?

Description clearly states it looks up dry-dock, survey, and IOPP dates plus technical manager contact. It distinguishes from sibling intel tools by specifying the exact resource type and mentions two usage modes (single vessel by imo/name or fleet scan with date range). The verb 'look up' and 'scan' are specific and 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?

Description gives context for when to use: when needing drydock/survey dates for a specific vessel or scanning a date range. However, it does not explicitly compare with sibling tools like intel_class or intel_inspections, nor does it state when not to use this tool. It mentions the Maritime Reports add-on for access, but no direct alternatives or exclusions.

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?

No annotations are provided, so the description carries the full burden. It accurately describes the return data and identification methods but does not disclose potential behaviors like data freshness, auth requirements, or error handling. For a read-only tool, this is adequate but not rich.

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 purpose, and contains no redundant information. Every sentence adds 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 has 4 parameters (none required) and an output schema, the description sufficiently explains the tool's functionality and input options. It covers what the tool returns and how to identify vessels. Slightly lacking in usage context but overall 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 baseline is 3. The description adds context for imo, name, and fuzzy (loose matching), but the updated_from parameter is only described in the schema. No significant additional semantics beyond 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 clearly states the tool returns the main-engine specification for a vessel, listing specific fields (engine model, builder, propulsion type, MCO). It distinguishes from sibling tools like intel_class and intel_companies by focusing on engine specs.

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 explains when to use (need main-engine specs) and provides identification guidance (imo/name, fuzzy matching). However, it does not explicitly contrast with other intel_* tools or specify when not to use it.

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?

With no annotations, description fully carries behavioral disclosure. It describes the check action and lists available features, implying a read-only operation. Could explicitly state no side effects, but is mostly adequate.

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?

Description is informative but slightly lengthy due to feature listing. However, the core purpose and usage are front-loaded in the first sentence, making it efficient for quick parsing.

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 no parameters, output schema existence, and sibling tool complexity, description fully explains what the tool does and what it returns (list of add-on features). No gaps remain.

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?

No parameters exist, so baseline is 4. Description adds no param info as none needed, and schema coverage is 100%.

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 uses specific verb 'check' and resource 'Maritime Reports add-on status', clearly distinguishing from sibling intel_* tools that focus on individual report types. It lists what the add-on offers, making intent 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?

Explicitly states when to use: when user asks about add-on status, when another tool indicates missing add-on, or after purchase/update. This provides clear context and exclusions implicitly by contrasting with specific data 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the output fields for a read operation, which is good. However, it does not mention error conditions (e.g., missing vessel), authentication requirements, or any restrictions like data freshness. The description is adequate but not thorough.

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 extremely concise at three sentences. The first sentence clearly states the primary action and output. The second sentence handles parameters, and the third provides context (add-on). Every sentence earns its place with no redundancy or unnecessary 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?

Given that an output schema exists, the description effectively covers the core purpose, identification methods, and date filtering. Minor gaps include no mention of what happens when both imo and name are provided, or when neither is provided (since no required parameters). Additionally, pagination or result limits are not addressed, but these are typical trade-offs for a retrieval tool.

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 baseline is 3. The description adds value by clarifying the purpose of each parameter: 'Identify the vessel by imo or name, and optionally bound the period with from / to.' It also summarizes the returned data, which goes beyond the schema's parameter-level descriptions. This helps an agent understand how to use the parameters effectively.

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 verb 'Retrieve' and the resource 'vessel's Port State Control (PSC) inspection record', and explicitly lists the fields returned (inspecting authority, port, type, date, detention, deficiencies). This distinguishes it from sibling tools like intel_casualties or intel_class which cover different aspects of vessel data.

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 no guidance on when to use this tool versus alternatives such as intel_casualties or intel_class. It does not specify prerequisites, limitations, or mention the required Maritime Reports add-on. The agent receives no help in choosing between similar intel_* 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?

No annotations are provided, so the description bears full responsibility. It discloses that the tool returns entity details (company IMO and country) and P&I club/flag, and explains the two lookup directions. No contradictions, and the behavioral traits are transparent enough for typical data retrieval.

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, efficient paragraph of three sentences that front-loads the main purpose and covers both modes without redundancy. It is concise and every sentence adds 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 7 parameters and the existence of an output schema, the description adequately explains the tool's behavior and usage. It covers both lookup modes and mentions the output elements. No gaps are evident.

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% coverage with descriptions for all 7 parameters. The description reinforces these by explaining the purpose of key parameters (e.g., 'use when the IMO is unknown' for name, 'returns every vessel under that operator' for operator). This adds context beyond the schema's basic 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 reveals commercial control of a vessel (beneficial owner, operator, managers, P&I club, flag) and distinguishes two usage modes: lookup by vessel or by company. It also identifies itself as part of the Maritime Reports add-on, differentiating it from sibling tools like intel_companies.

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 reveal commercial control) and provides two usage modes. Although it does not explicitly list when not to use it or compare to siblings, the context of the tool is clear from the purpose statement.

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?

Describes async nature, return values (report_id, _PENDING_ status), and polling requirement. Mentions server never downloads file. No annotations provided, so description carries burden; it does well but could mention rate limits or idempotency.

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?

Four compact sentences, each adding essential information: purpose, sibling differentiation, async workflow, and server behavior. No redundancies.

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 single parameter, existing output schema, and many siblings, the description fully covers the async job semantics, differentiation from lookup tools, and the polling workflow. Leaves no ambiguity.

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% and already lists report_type values. Description adds context that report_type selects a bulk dataset and reinforces full-dataset behavior, adding value beyond 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?

Clearly states the tool submits an async job to export a full bulk dataset for Maritime Reports add-on datasets. Lists specific report types and distinguishes from single-vessel lookup 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?

Explicitly says when to use (for bulk datasets) and when not to (for a single vessel, use matching lookup). Explains async workflow: submit once, poll report_status, then hand result_url to user.

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?

With no annotations provided, the description fully carries the burden of behavioral disclosure. It clearly indicates the operation is a retrieval (no side effects), and enumerates output fields (seller, buyer, price, price per lightweight ton, demolition destination). It does not explicitly mention rate limits or authentication, but the 'Part of the Maritime Reports add-on' hint implies a prerequisite.

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 extremely concise: two sentences with no wasted words. The first sentence immediately states the tool's purpose and output, while the second provides practical usage guidance. All information is front-loaded and 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 the moderate complexity (4 optional parameters, output schema present, no nested objects), the description covers purpose, use cases, parameter roles, and output fields. It mentions the 'Maritime Reports add-on', which implies a prerequisite. A minor gap is the lack of explicit mention of authentication requirements or data freshness, but overall it is sufficiently 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% with each parameter already described in the input schema. The description adds minor value by grouping parameters into identification (imo/name) and period bounding (from/to), but does not significantly extend meaning beyond the schema. Thus, 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 the specific verb 'Retrieve' and clearly defines the resource as 'ship sale-and-purchase transactions for a vessel: second-hand sales, newbuilding deliveries and demolition (scrap) sales'. It lists concrete output fields (seller, buyer, price, etc.) and distinguishes itself from sibling tools (e.g., intel_casualties, intel_class) by focusing uniquely on sale/purchase/demolition data.

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 clear context for when to use the tool ('useful for asset valuation and market tracking') and explains how to identify vessels (by imo or name) and optionally bound by date. However, it does not explicitly state when not to use it or mention alternative tools among the siblings, though the siblings are sufficiently distinct.

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?

With no annotations, the description discloses that it lists only the caller's jobs, statuses, and result_url when done. It omits details like pagination, sorting, or rate limits, but is adequate for a simple tool.

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 with no wasted words. Key information 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?

Given no parameters and an output schema, the description covers purpose and use case. It could mention if results are limited or sorted, but overall 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?

Since there are no parameters, schema coverage is 100%. The description adds context about 'recent' and 'caller's jobs', which is helpful beyond the empty 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 clearly states it lists the caller's recent async report jobs with statuses and result_url, and distinguishes it from sibling tools like report_request and report_status.

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 to use it to recover a report_id or check completion, and provides an example. It lacks explicit when-not-to-use but is 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?

No annotations are provided, so the description carries full responsibility. It fully discloses asynchronous behavior: 'Reports are generated in the background... returns a report_id and an initial status... it does NOT wait.' It describes the polling mechanism, how to get the result URL, and that the server never downloads files itself. This is thorough behavioral disclosure.

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 an introductory paragraph, a bulleted list of report types, and a closing note. Every sentence contributes meaning, but it is slightly verbose (e.g., 'it's good to tell the user before submitting' could be more concise). However, it is well-organized and front-loads the key async process.

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 6 parameters, async behavior, and an output schema, the description covers everything an agent needs: how to initiate, poll, and retrieve results, plus credit cost warnings. It also provides per-report-type parameter requirements. It is complete and leaves no critical gaps for correct usage.

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 documents all parameters. The description adds integrated context beyond individual parameter descriptions: it explains which parameters are required for each report_type, date constraints (≤31 days for request_usage, ≤7 days apart for inradius_history), and radius max (50 NM). This is valuable semantic enrichment beyond the schema's declarative 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 'Submit an async report job' and lists all supported report types with details. It distinguishes itself from sibling tools like intel_report_request by explicitly noting that for add-on bulk datasets, that tool should be used instead. The verb 'submit' and resource 'async report job' are specific and 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?

The description provides explicit when-to-use instructions: 'Submit ONCE, then poll report_status with the returned report_id until _DONE_... Do not resubmit while a job is running.' It also tells when not to use it: 'For the add-on bulk datasets... use intel_report_request instead.' Additionally, it warns about credit consumption for certain report types, guiding the agent to inform the user before submitting.

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?

With no annotations, description fully discloses behaviors: statuses, waiting instructions, link expiry, and that server never downloads. Highly transparent.

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?

Concise, front-loaded with key action, no redundant sentences. Every sentence adds necessary information.

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 output schema exists, description covers all needed user-facing behavior (statuses, link handling) without needing to detail return fields.

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 has 100% description coverage. Description adds value by specifying the origin of report_id (from report_request or report_list), aiding correct invocation.

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 the tool checks an async report job by report_id, distinguishing it from siblings like report_request and report_list.

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 clear guidance on when to use and what to expect for each status, including handling of time-limited links. Does not explicitly state when not to use, but context is sufficient.

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?

No annotations provided; description fully covers behavioral traits: schematic nature, no real-world navigation, return format, distance units, and add-on context.

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 concise sentences plus necessary warning, front-loaded with main action, no redundancy.

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 output schema exists, description covers inputs, output, limitations, and appropriate use cases comprehensively with no gaps.

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 has 100% coverage; description adds value by grouping parameters into three alternative spec methods (coordinates, UUID, UN/LOCODE), clarifying usage beyond 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?

Description clearly states the tool calculates a schematic sea route, returns GeoJSON LineString with distance, and distinguishes from siblings by specifying 'schematic' and not navigable.

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 describes when to use (estimating distance, visualizing path) and when not to use (real-world sailing). Lacks explicit alternative among siblings, but provides strong context.

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