Roman numerals

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

Annotations already declare readOnly/idempotent/closed-world, so the description correctly focuses on capability semantics: strict validation that reports specific malformed forms (IIII, IC, VV, IIX) and returns symbol-by-symbol working, plus hard limits (1–3,999 standard, 3,999,999 with vinculum). The date mode's year bound of 1–3999 is useful extra context not in the schema.

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 paragraph with the primary conversion described first, then date mode, then a link. The stacked parentheticals make it slightly heavy to scan, and the web-version URL is marginal for an agent, but nothing is genuinely 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?

With 6 parameters, no output schema, and full annotation coverage, the description adequately covers all three modes, input limits, and failure behavior. The one real gap is that with no output schema present, it never sketches the response shape (e.g., what the returned string or validation breakdown looks like).

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, but the description earns more by explaining the range semantics behind `number` (including the ×1,000 vinculum rule) and the date year bound, which the schema only implies. It does not explicitly tie each parameter name to its mode, but the schema descriptions already do that.

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 in both directions (numbers → Roman numerals and back), plus a third date-formatting capability. It is immediately distinguishable from neighbors like base_convert or text_number_to_words because it names the domain, the accepted range, and the vinculum extension.

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?

Each mode's job is spelled out in prose (convert to Roman, validate/parse back, format a date), so an agent can map intent to the correct `mode` value without guessing. It stops short of explicitly naming alternatives (e.g., base_convert for other numeral systems) or stating 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.