Crystals by Purpose

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world. The description adds the matching behavior ('substring-matches against purpose tags') and a cost caveat ('not in the public credit manifest'), which is genuinely useful. However, the substring claim duplicates the schema, and nothing is said about response shape, result limits, or ordering — though an output schema exists, so that gap is mild.

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 core sentence is front-loaded and complete; the bracketed metadata block (group, endpoint, required, cost) is scannable. Slight redundancy between the description's substring sentence and the schema's substring note.

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?

A single-parameter read-only lookup with an output schema and full annotation coverage needs little more than this. The only meaningful omissions are sibling disambiguation and any hint about result volume or ordering.

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 the schema already explains substring matching with the 'protect → protection' example. The description restates the matching semantics but adds no new syntax, format, or constraint information beyond what the parameter schema provides.

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 ('Crystals indexed by intent keyword') with concrete example keywords, which is more informative than the title alone. It doesn't explicitly differentiate from close siblings like astroway_esoteric_crystals_recommend or astroway_esoteric_crystals_by_chakra_chakra, so the agent must infer 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?

Usage is implied by the keyword examples (love, prosperity, healing, protection) and the 'Required: purpose' note, so an agent can guess when to call it. There is no explicit statement of when to prefer this over crystal recommendations, chakra lookup, or zodiac lookup, and no exclusions.

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