I Ching Hexagram (DEPRECATED: use /iching/throw-coins)

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

Goes well beyond the annotations by disclosing deprecation status, removal date, cost (10 credits, Tier 1), endpoint, that the cast is random/non-reproducible, and that input is ignored. One minor tension: it calls the cast 'random' while the annotations carry idempotentHint=true, which an agent could read as promising repeatable output — worth a note but not a destructive/read contradiction.

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?

Front-loads 'DEPRECATED' and the replacement, so the critical routing signal lands first. Slightly redundant with the trailing [⚠️ DEPRECATED] footer and the metadata tags, but every sentence otherwise 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?

An output schema exists so return values need no explanation, there are no params to document, and annotations cover safety. The description closes the remaining gaps — deprecation lifecycle, replacement set, cost, and the fact that inputs are ignored — so nothing an agent needs to decide or call correctly is missing.

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?

Zero parameters, so the baseline is 4; the description still adds value by stating explicitly that 'input is ignored', which prevents an agent from hunting for a required seed or question field that the successor tools accept.

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 — 'Casts a single I Ching hexagram' — and immediately scopes it as the 'legacy un-namespaced random hexagram cast', which separates it from the astroway_iching_* siblings it names by path. An agent knows exactly what this does and which family it belongs to without opening any 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?

Explicitly tells the agent to avoid this tool and routes to `/iching/throw-coins` (seeded + reproducible), plus lists by-question, with-changing-lines, daily and lookup as alternatives, with a concrete 2027-06-16 sunset date. This is a textbook when-not/alternative structure.

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