ALUZZA MARINE: Japan boat trade and tide tables

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

With no annotations, the description carries the full behavioral burden and does add real value: it declares the data source as JMA astronomical tide estimation rather than a forecast, and bounds the date range to 2026-01-01 through 2027-12-31. It omits failure behavior (out-of-range dates, unknown stations) and the shape of the returned tide table, leaving notable gaps for an unannotated 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?

The returned data is front-loaded in the first clause, with the range limit, the days option, the hourly option, and the data-source caveat each in compact trailing fragments. Dense but every fragment carries information; no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description must describe return values, and it does enumerate the fields returned (tide times, levels in cm from the datum, moon age, tide type, moon phase). Given a simple 4-parameter read tool, this is nearly complete, with only error/edge-case behavior and the unit/shape of hourly output left unstated.

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 all four parameters are already documented, and the description mostly restates them (days up to 7, include_hourly for hourly levels). The only marginal addition is the framing of the station-name-vs-code ambiguity, which the schema already describes. Baseline 3 applies when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the specific resource set it returns (high/low tide times and levels, moon age, tide type, moon phase) for a given station and date, with an explicit valid date range. It distinguishes itself from weather siblings by stating it is JMA astronomical tide calculation, not a forecast, but it never names the closest siblings (next_tide, list_tide_stations) to sharpen the boundary.

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 gives implied usage cues (days for up to 7 consecutive days, include_hourly for hourly levels) and notes that ambiguous station names return candidates, which guides the call pattern. However, it never states when to prefer it over next_tide or how to first resolve a station via list_tide_stations, so the agent must infer the alternative routing.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that the tool returns quantity and value in yen and that partner filtering is optional, but it does not describe output structure, quantity units, data source, or any permission/rate-limit behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two compact sentences with the main return behavior front-loaded and the optional partner behavior immediately after. There is no wasted wording.

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 fully described four-parameter schema and the absence of an output schema, the description is largely complete: it names the returned quantity/value data and explains partner filtering. The main omission is sibling-tool routing, which is relevant because top_partners and yearly_series appear to cover related trade queries.

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

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

Schema description coverage is 100%, so the schema already documents year, flow, hs, and partner. The description adds a useful special partner value, “世界の合計,” for overall totals, but otherwise adds little 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 states a specific action and resource: it returns quantity and yen value by country for a given year, flow, and HS item. This is clear enough for an agent to understand the tool, but it does not distinguish get_trade from related siblings such as top_partners or yearly_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 explains how to use the optional partner parameter, but it gives no guidance on when to choose get_trade instead of sibling tools like top_partners or yearly_series. There are no explicit alternatives, prerequisites, or exclusion conditions.

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 exist, so the description carries the full burden. It does disclose the return contents (codes, JP/EN names, data caveats), which is genuinely useful. It says nothing about output format, whether results are paginated or cached, or how the returned codes are meant to be consumed downstream.

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 short sentences, front-loaded with what is returned and followed by the usage recommendation. No filler. The phrasing is slightly vague ('間違えにくい') but earns its place as actionable guidance.

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 no output schema and no annotations, the description must supply the shape of the result, and it only sketches it (codes, two name languages, caveats). Critically, it never says the codes are the input vocabulary for sibling tools such as get_trade, which is the main reason an agent would call this first.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; baseline 4 applies. The description correctly implies a parameterless enumeration rather than a lookup requiring input.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (returns/使える) and resource: available item codes plus names in Japanese and English, plus data caveats. That is more than a restatement of the name 'list_codes'. It does not, however, connect itself to the sibling family (get_trade, top_partners, yearly_series), so an agent cannot tell from the description whether 'code' means commodity codes for trade statistics.

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?

Gives explicit sequencing guidance: call this first and you are less likely to make a mistake. That is a clear when-to-use signal, which is rare. It stops short of naming alternatives or saying what to do once the codes are retrieved.

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 disclosure burden. It usefully reveals the fixed catalogue size (239 stations) and the default zero-argument behavior, but says nothing about whether results are paginated, how matching is done (partial match/prefix), or what a populated response looks like.

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 short sentences with the resource and catalogue size front-loaded, then per-parameter guidance, then the default case. No filler and nothing an agent must read past to reach the essential facts.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-optional-parameter lookup tool with no annotations and no output schema, the description covers purpose, parameter usage, and the no-argument fallback. Only the shape of the returned station records is left implicit, which is a minor gap.

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 both parameters are already documented in the schema, including the 2-character code form (e.g. TK). The description adds place-name examples and the joint omission behavior, but it does not explain matching semantics or whether the two parameters combine as AND or as alternatives.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (find tide stations) and quantifies scope (239 locations in the JMA tide table), which lets an agent distinguish it from data-returning siblings like get_tide or next_tide. It does not, however, explicitly name those siblings as alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explains how each parameter selects results (place name → query, region → region) with concrete examples, and says what happens when both are omitted (region list with station counts). That is clear usage context, but there is no explicit 'use this instead of get_tide when…' routing 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 carries the burden and does well: it enumerates what is returned (times, levels, minutes-to-event, current level, rising/falling, tide cycle, speech_ja) and states an important caveat — it is JMA astronomical tide calculation, 'not a forecast'. That caveat is genuinely valuable context a schema cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One dense but front-loaded paragraph with no filler; the core scope leads and the caveat and speech_ja note trail as supporting detail. Nothing is redundant.

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 no output schema, the description appropriately spells out the returned fields and the not-a-forecast caveat, and the params are fully covered by the schema. Minor gaps (units or precision of tide level, error behavior for unknown station) keep it from a 5.

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 both parameters are already documented. The description's 'at で別の時刻も' restates the schema's at parameter rather than adding new syntax or format detail, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb (返す) and precise resource: next high tide, next low tide, current tide level, rising/falling state, and tide cycle, all from Japan time now. It is clearly distinguishable by its 'next + current' scope, though it never explicitly separates itself from the sibling get_tide, so it falls short of full sibling 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?

'いま（日本の時刻）から見た' and 'at で別の時刻も' imply when to use it (point-in-time snapshot) and how to shift the reference time. But there is no explicit when-not guidance and no routing to get_tide or list_tide_stations, leaving usage to inference.

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 disclosure burden and does well: it names the data source (JMA observations), the historical start (1991), the 40 km station-proximity rule, and the output granularity implied by each parameter combination. It omits failure behavior when no station falls within 40 km and any rate/auth constraints.

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?

Resource and constraints are front-loaded in the first clause, followed by the combination rules. It is dense but nearly every clause carries operational information; only the closing 'not a forecast' restates a point already implied by '過去'.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 3-parameter read tool with no annotations and no output schema, the definition covers source, time range, spatial constraint, and granularity rules well. The remaining gap is the return shape (units, which metrics come back per row), which the agent must infer.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining the interaction of year and month — the semantics of each combination is nowhere in the schema, which only labels them '年' and '月'. The station parameter meaning is largely repeated from the schema rather than extended.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific retrieval (past monthly average temperature, wind speed, precipitation) tied to a named, constrained resource (nearest JMA station within 40 km of the port, data from 1991 onward). It explicitly distinguishes itself from forecast-style tools with '過去の観測で、予報ではない', so an agent can tell what it is and is not without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an exhaustive mapping of when each invocation shape applies: year only → 12 months of that year, month only → that month across years, both → a single month, neither → latest 12 months. That is strong usage context, but it never names a sibling tool or an exclusion condition (e.g. use get_tide instead for tide data), so it falls short of a 5.

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

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

No annotations exist, so the description carries the full burden. It does usefully disclose a derived output (per-unit average price in yen) and the descending sort, which are not in the schema. But it omits the default count (10, per schema) and max (50), and says nothing about whether results are single-year or aggregated across the year range.

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 compact sentences with the scope stated first and the extra output (average unit price) appended. No filler, though it is arguably terse enough to leave gaps rather than dense.

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 six parameters, no annotations and no output schema, the description should explain what comes back. It mentions country ranking plus average unit price but leaves unclear whether year_from/year_to produce a single aggregated ranking or per-year rows, and does not cover the limit parameter.

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 every parameter has an enum or example-rich description, so the baseline is 3. The description restates the same scope dimensions (year range, flow, HS) without adding syntax, defaults or format detail 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 states a specific operation: rank partner countries in descending order of quantity or value, scoped by year range, flow and HS code. That is more precise than the bare name, but it never names the sibling it differs from (get_trade, yearly_series), so an agent must infer the distinction.

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?

Usage is only implied by the stated scope: an agent can guess this is for 'top N partners' style questions. There is no explicit when-to-use, no exclusion against get_trade or yearly_series, and no mention of when to prefer quantity ranking over value ranking beyond the schema's enum.

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 must carry the behavioral burden. It discloses that this is a read-style data retrieval tool, the date range, currency unit, and default aggregation behavior, but it does not mention permissions, missing-year handling, or response structure.

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 compact clauses with no wasted text, front-loading what is returned and following with the default partner behavior.

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 no output schema, the description appropriately explains that yearly quantity and amount in yen are returned across 2011–2025. The parameter schema is fully documented, so the main remaining gap is lack of detail about missing years or output shape.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description repeats the partner omission behavior that is already stated in the schema and adds no additional syntax or semantic detail, making the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns yearly quantity and amount in yen for 2011–2025, sliced by flow, item, and partner country. It does not explicitly differentiate itself from siblings such as get_trade or top_partners, so it stops short of a 5.

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 provides one useful usage rule: omitting partner returns the world total. However, it gives no guidance on when to use this tool versus get_trade or top_partners, leaving sibling selection implicit.

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