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

With no annotations supplied, the description carries the full disclosure burden, and it does substantial work: it defines the comparison baselines (Jan-Oct 2023 normal and last year), the 7-day averaging of transits, the 0-100 Stress Index scale with 100 meaning the worst week since 2023, and the Suez share metric. It still omits operational traits such as read-only vs mutating nature, refresh cadence of the daily data, and response size, so it is strong but not complete.

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?

A single, densely packed sentence that front-loads the core resource and transits metric before drifting into secondary metrics. The parenthetical chokepoint list and the trailing '...' add bulk, but nearly every clause carries distinct information, so it earns most of its length.

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?

There is no output schema and no annotations, yet the description explains the returned metrics, their baselines, and the index scale well enough that an agent knows what to expect. Remaining gaps are minor: the exact response shape, the age or refresh cadence of the 'daily' figures, and any note that the operation is a read.

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. The description adds some meaning by enumerating the chokepoint universe (28 total, naming Hormuz, Bab el-Mandeb, Suez, Cape of Good Hope, Panama, Malacca, Bosporus, Gibraltar), which helps an agent choose valid name fragments. It says nothing about the weeks parameter beyond implying the Stress Index has history, so this sits at the baseline.

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 resource (maritime chokepoint monitor) and enumerates exactly what it reports: daily 7-day-average transits, comparison against a Jan-Oct 2023 normal and last year, status flags, cargo mix, the Chokepoint Stress Index, and the Suez share. That is far more specific than a name restatement. It does not explicitly differentiate itself from siblings such as get_trade or get_weekly_pulse, which keeps it at 4 rather than 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?

Usage is only implied: the phrase 'chokepoint monitor' and the metric list suggest it is the tool for shipping-lane disruption questions, and 'omit for all' hints at browsing versus targeted lookup. There is no explicit statement of when to prefer this over get_trade or get_weekly_pulse, and no exclusions or prerequisites.

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