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

No annotations are provided, so the description carries the full behavioral burden, and it discloses only deprecation status. It does not say whether the tool still functions, whether calls will error or silently return stale values, whether removal is scheduled, or what credentials/rate limits apply. The deprecation notice is genuinely useful context but is the only behavioral signal present.

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 sentence, front-loaded with the deprecation warning ahead of the functional description, which is the correct priority for a retired tool. The trailing "Calculate Port Congestion Index" largely restates the tool name, making it slightly redundant but not wasteful.

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 1-parameter tool with no output schema, the only thing an agent truly needs is the replacement and whether this tool is still callable — only the first is answered. Missing are parameter format guidance, expected return shape, and the operational status of the deprecated endpoint, leaving an agent unable to decide whether to call it at all.

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 single parameter port_id has 0% schema description coverage and the description says nothing about it — no format, no valid-value source (list_supported_ports is a sibling that likely supplies IDs), no required-ness context. Since coverage is below 50%, the description needed to compensate and does not.

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+resource ("Calculate Port Congestion Index") and immediately flags deprecation, which distinguishes it from the active sibling get_port_congestion_risk. It does not explain what the index measures or how it relates to the replacement, so the agent knows what it computes only at surface level.

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 routes the agent away from this tool: "Use get_port_congestion_risk instead" names the alternative directly. It stops short of a full when/when-not treatment — no indication of whether this tool still returns valid data, or whether the replacement is an exact equivalent, so an agent cannot judge fallback behavior.

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