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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds that it returns 'normalized schedules with upstream source metadata', which provides some context about the output. However, it does not disclose other behavioral traits like rate limits, authentication requirements, or error handling, but given the annotations, the bar is lower. The description adds moderate value.

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, front-loaded with the core purpose and criteria, followed by the return type. No redundant or extraneous information. Every word 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 18 parameters, nested objects, no output schema, and zero required parameters. The description is brief and does not explain complex credential parameters, pagination (limit), provider selection, or fallback policies. Given the complexity, the description is incomplete and leaves significant gaps for an AI agent to use the tool effectively.

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 0%, so the description must compensate. It lists the main filtering parameters (origin/destination, carrier, cargo type, direct-only, date windows), but omits many technical parameters like limit, provider, credentialProfile, oneTimeCredential, fallbackPolicy, and coverageHint. The description adds some meaning but is insufficient to fully understand all 18 parameters.

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 searches carrier sailing schedules and lists specific search criteria (origin/destination, carrier SCAC/name, cargo type, direct-only flag, departure/arrival windows). The verb and resource are explicit, and the purpose is distinct from sibling tools like vessel_schedule or schedule_delay_predict, even without explicit 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?

The description provides no guidance on when to use this tool versus alternatives, such as vessel_schedule or port_calls. There are no context hints or exclusion criteria, leaving the agent to infer usage from the tool name alone.

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 indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds a behavioral guarantee that raw keys are never returned, which is a security-related transparency not captured by annotations. 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?

Two concise sentences, front-loaded with the action and results. No extraneous words. The second sentence adds critical 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 presence of an output schema and the simplicity of a parameterless list tool, the description covers all necessary aspects: what is returned, what is not, and safety implications. Users have enough context to invoke 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 input schema has 0 parameters, so baseline is 4. The description adds value by explaining what the output contains (labels, provider hints, field names, status) and a security constraint. This enriches understanding 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?

The description clearly specifies the action ('List'), the resource ('BYOK credential profile'), and the exact fields returned (labels, provider hints, declared field names, status). It also distinguishes itself by noting what is not returned ('Raw keys are never returned'), making it 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 lacks explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites or scenarios where other tools might be preferred. However, the tool's purpose is straightforward and self-contained, so the absence is less critical.

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, destructiveHint, idempotentHint. The description adds context about the type of information returned (coverage notes, auth mode, caveats), but does not disclose any additional behavioral traits like pagination or rate limits.

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 sentence of 10 words that conveys the essential purpose and output. No redundant or filler 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 zero parameters and presence of output schema and annotations, the description is sufficient. It specifies what is listed, covering the tool's complete functionality for this simple operation.

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 has zero parameters with 100% coverage, so the description does not need to add parameter meaning. Baseline for zero parameters is 4, and the description correctly omits parameter details.

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 'List' and resource 'vessel data source adapters', clearly stating the output includes 'coverage notes, auth mode, and caveats'. This differentiates it from sibling tools that query specific 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?

No explicit guidance on when to use this tool versus alternatives. The description only states what it does, not when it should be chosen over siblings like carrier_schedule_search or vessel_search.

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, destructiveHint, and idempotentHint. The description adds that the tool returns ranked candidates but does not disclose other behaviors like error handling or performance.

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 sentence that front-loads the core purpose without unnecessary 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 tool's complexity (8 parameters, no output schema, multiple credential options), the description is far too brief and lacks essential details for correct 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?

Schema coverage is 0% and the description does not explain any of the 8 parameters, including complex nested objects like hint and credentialProfile, making it impossible for the agent to know how to provide inputs.

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 (extract) and resource (vessel signals from B/L-style text), and the mention of 'ranked candidates' differentiates it from sibling tools like vessel_search or 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 implies usage with B/L-style text but provides no explicit when-to-use or when-not-to-use guidance relative to siblings like carrier_schedule_search or vessel_track.

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 indicate readOnly and idempotent behavior, but the description adds no extra context about the return format, pagination, or what 'recent' means.

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 very short and front-loaded, but may be too concise given the tool's complexity, omitting important parameter 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?

Given 9 parameters, no output schema, and nested objects, the description provides insufficient detail for correct 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?

With 0% schema description coverage, the description explains only mmsi, imo, and portUnlocode as filters, ignoring the 6 other parameters like credentialProfile and fallbackPolicy.

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 recent port-call events for a vessel by MMSI/IMO or for a UN/LOCODE port, which distinguishes it from sibling tools like vessel_position or vessel_schedule.

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 mentions 'Requires at least one filter' but does not elaborate on when to use this tool over alternatives or specify 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds explicit context by stating 'Does not create accounts or issue credentials', reinforcing the non-destructive nature. It also details what information is shown (signup, docs, env vars, status, validation steps), which 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 two sentences, concise and front-loaded with the main purpose. The second sentence adds a crucial negative clarification. It could be improved by integrating parameter hints, but overall efficient.

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 the tool has an output schema and annotations covering safety, the description adequately states purpose and behavioral guardrails. However, it lacks any guidance on the parameters (provider, capability, implementedOnly) and does not mention any prerequisites or special cases, leaving some gaps for an agent to interpret.

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 0%, so the description must compensate. However, it does not explain the three parameters (provider, capability, implementedOnly). The description only mentions 'provider access' generically, with no mapping to the specific inputs or their allowed values (e.g., the enum for capability). This leaves the agent without clear guidance on how to populate the parameters.

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 shows onboarding steps, API docs, credential env vars, status, and validation steps, and explicitly says it does not create accounts or issue credentials. This effectively distinguishes it from sibling tools like provider_status (focused on status) and credential_profiles (focused on credentials).

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 use when onboarding information is needed (e.g., to view setup steps or status) but does not explicitly state when to use this tool versus alternatives like provider_status or credential_profiles. No exclusions or when-not-to-use guidance is provided.

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 indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds the term 'caveats' but does not elaborate on behavioral details such as rate limits or response size. It is adequate but adds little 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 a single sentence front-loaded with the action and resource. Every word is meaningful; no redundancy. It is appropriately sized.

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 zero parameters, rich annotations, and presence of an output schema, the description covers all necessary context: it states what the tool lists and what aspects are included. The output schema provides further details, so completeness is high.

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?

There are zero parameters, so schema coverage is 100%. Per guidelines, baseline is 4. The description does not need to add parameter info, and it doesn't.

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 specific verb 'List' and resource 'configured vessel data providers', and enumerates the types of information included (auth state, feature support, quota hints, caveats). It clearly distinguishes from siblings like 'carrier_schedule_search' or 'credential_profiles' which have different purposes.

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 does not provide explicit guidance on when to use this tool versus its siblings. There is no mention of when not to use it, prerequisites, or context. The agent must infer usage from the tool name and list of contents.

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 indicate readOnly, idempotent, and non-destructive behavior. The description adds context about the heuristic logic (comparison of timestamps) and the output categories, which is helpful 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 a single, well-structured sentence that immediately states the action and output. No unnecessary words or 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 7 optional parameters and no output schema, the description is too brief. It does not explain which parameters are needed for different scenarios, the heuristic logic, or what the output looks like. More detail is needed 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 description coverage is 0%, so the description must compensate but fails to do so. It does not explain any of the seven parameters individually or how they relate to each other. The description only vaguely references 'timestamps' without specifying which parameter corresponds to what.

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 ('Compare'), the resources ('planned carrier schedule timestamps with estimated/actual timestamps'), and the output ('on-time, at-risk, delayed, or unknown heuristic'). It distinguishes itself from sibling tools like carrier_schedule_search and port_calls by focusing on delay prediction.

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 this tool is for comparing timestamps to predict delays, but it does not provide explicit guidance on when to use it vs. alternatives, nor does it mention any prerequisites 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?

Annotations already indicate a safe, idempotent read operation. The description adds that results are 'latest known positions' with 'provider source metadata' and bounding box constraints, but does not disclose pagination, error handling, or rate limits. Some value added 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?

Single sentence with no fluff, front-loading the core action and key constraint. Every word 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 tool's complexity (7 parameters, nested credential objects, no output schema), the description is too minimal. It omits how to use credential profiles, the meaning of fallbackPolicy and coverageHint, and the output format. Incomplete for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description should compensate but only mentions bounding box. Parameters like limit, provider, credentialProfile, oneTimeCredential, fallbackPolicy, and coverageHint are unexplained. The description adds minimal meaning beyond the schema structure.

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 latest known positions for vessels within a bounding box, including coordinate constraints and provider source metadata. This distinguishes it from sibling tools like vessel_position (single vessel) and vessel_track (time series).

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 use for area-based queries via bounding box but does not explicitly contrast with alternatives like vessel_position or vessel_track for single vessels or tracking. No when-not-to-use guidance is provided.

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, idempotentHint=true, and no destructiveness. The description adds context by specifying the output is 'ranked MMSI/IMO candidates with matched/missing signals and confidence', which goes beyond annotations. It does not contradict 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 a single sentence that is concise and front-loads the core functionality. Every part is meaningful and no unnecessary 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 tool's complexity (14 parameters, no output schema), the description is insufficient. It does not explain the many optional parameters, authentication options, or return format beyond 'ranked candidates'. More details are needed for an AI agent to use 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?

With 14 parameters and 0% schema description coverage, the description should compensate but does not. It only mentions 'messy vessel name' without explaining other key parameters like provider, credentialProfile, fallbackPolicy, or limit. The added meaning over the schema is minimal.

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 resolves messy vessel names to ranked MMSI/IMO candidates, using a specific verb 'Resolve' and resource 'vessel name'. It distinguishes itself from siblings like vessel_search by focusing on fuzzy matching from B/L text.

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 usage when a messy vessel name is available (e.g. from B/L text) but does not explicitly state when to use this tool versus alternatives like vessel_search or vessel_track, nor does it mention any exclusions or prerequisites.

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 idempotentHint=true, and the description adds value by specifying that the return includes source, retrievedAt, observedAt, and freshness metadata. 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?

The description is a single, front-loaded sentence with no filler. Every word contributes to understanding the tool's 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?

Given the complexity of 7 parameters including authentication/providers and no output schema, the description falls short. It does not address authentication requirements, credential handling, or fallback policies, which are crucial for execution.

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 0%, so the description must add meaning beyond parameter names. It only clarifies MMSI/IMO but omits explanations for provider, credentialProfile, oneTimeCredential, fallbackPolicy, and coverageHint, leaving most parameters semantically under-explained.

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 latest known position for a vessel by MMSI or IMO' using a specific verb and resource, and distinguishes from sibling tools like vessel_track (historical) and vessel_search (finding 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?

No explicit guidance on when to use this tool versus alternatives such as vessel_track for historical data or vessel_area for area-based queries. The description implies it's for the latest position but lacks 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 indicate the tool is read-only, non-destructive, and idempotent. The description adds that results include source metadata, but does not disclose other behavioral aspects like rate limits, pagination, or data freshness. 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 a single, concise sentence that efficiently conveys the core purpose. However, it could be restructured to break down key aspects (e.g., identifiers vs. filters) without increasing verbosity.

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 (13 parameters, nested objects, no output schema), the description is insufficient. It does not explain return values, required parameter combinations, credential usage, or how to narrow results with time windows and filters. A more comprehensive description is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage and 13 parameters, the description only explains identifiers (mmsi, imo, etc.) but fails to clarify parameters like windowStart, windowEnd, limit, provider, credentialProfile, oneTimeCredential, fallbackPolicy, and coverageHint. This leaves significant semantic gaps for correct usage.

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 scheduled carrier port calls for a vessel, listing multiple identifiers (MMSI, IMO, vessel name, voyage number, carrier SCAC) and source metadata. It effectively distinguishes from siblings like 'carrier_schedule_search' and 'port_calls' by focusing on vessel-specific schedule retrieval.

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 siblings like 'carrier_schedule_search' or 'port_calls'. It lacks instructions on prerequisites, combinations of parameters, or scenarios where this tool is preferred/avoided.

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, destructiveHint=false, idempotentHint=true. The description adds that results are 'normalized identities with provider source metadata', which provides behavioral context beyond annotations. 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 two sentences, front-loaded with the action and resource, then the requirement. Every word serves a purpose with 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 tool has 10 parameters, nested objects, and no output schema, the description covers only the identifier parameters and basic return concept. It lacks details on authentication, filtering, and policy options, making it incomplete for practical use.

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 0%, so the description must compensate. It names four identifier parameters (MMSI, IMO, name, callsign) and states the requirement for at least one. However, it omits explanations for limit, provider, credential objects, fallbackPolicy, and coverageHint, leaving significant gaps.

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 searches vessels by specific identifiers (MMSI, IMO, name, callsign) and returns normalized identities with provider metadata. It differentiates from sibling tools like vessel_area or vessel_position which serve different functions.

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 requires at least one identifier, which is a useful usage condition. However, it does not provide when-not-to-use guidance or mention alternative tools like vessel_name_resolve for name-only searches.

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 indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds 'recent' and time-bounding, but does not disclose pagination, data limits, or credential behavior. With annotations covering safety, a 3 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?

Single sentence, front-loaded with key information. No filler or redundancy. Achieves maximum efficiency.

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 annotations, the description omits essential context: return format, credential handling, provider selection logic, fallback and coverage semantics. With 9 parameters, nested objects, and no output schema, the description is too sparse.

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 0%. The description only mentions MMSI/IMO and time window parameters, leaving 5 undocumented parameters (provider, credentialProfile, oneTimeCredential, fallbackPolicy, coverageHint) unexplained. This fails to compensate for the schema gap.

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 recent track points for a vessel by MMSI or IMO, with optional time bounds. It uses specific verbs and resources, and distinguishes from siblings like vessel_position (likely current position) and vessel_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?

No explicit guidance on when to use this tool versus alternatives (e.g., vessel_position for current position, port_calls for port events). The description implies historical track retrieval but does not outline scenarios or exclusions.

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