search_spell

Search and retrieve D&D 5e spells using the repository pattern.

This tool provides comprehensive spell lookup functionality with support for filtering by multiple criteria. Results include complete spell descriptions, components, damage, effects, and availability information. Automatically uses the database cache through the repository for improved performance.

The repository pattern handles caching transparently:

• First call: Fetches from API and caches in database

• Subsequent calls: Returns cached results if available

• Supports test context-based repository injection via _repository_context

Examples: Search for spells: spells = await search_spell(search="fireball") spells = await search_spell(search="healing restoration")

Filtering by level:
    cantrips = await search_spell(level=0)
    high_level_spells = await search_spell(level=5)

Using level ranges:
    mid_level_spells = await search_spell(level_min=3, level_max=5)
    powerful_spells = await search_spell(level_min=5)
    beginner_spells = await search_spell(level_max=2)

Filtering by school and other properties:
    evocation_spells = await search_spell(school="evocation")
    wizard_spells = await search_spell(class_key="wizard")
    ritual_spells = await search_spell(ritual=True)
    concentration_spells = await search_spell(concentration=True)

Filtering by damage type:
    fire_spells = await search_spell(damage_type="fire")
    cold_spells = await search_spell(damage_type="cold")
    necrotic_spells = await search_spell(damage_type="necrotic")

Filtering by document:
    srd_only = await search_spell(documents=["srd-5e"])
    srd_and_tasha = await search_spell(documents=["srd-5e", "tce"])

Complex queries combining multiple filters:
    evocation_fire_spells = await search_spell(
        school="evocation", damage_type="fire"
    )
    cleric_rituals = await search_spell(
        class_key="cleric", ritual=True, level_min=1
    )
    mid_level_wizard_spells = await search_spell(
        class_key="wizard", level_min=3, level_max=5, limit=10
    )

Semantic search (natural language queries):
    fire_spells = await search_spell(search="fire damage explosion")
    healing_spells = await search_spell(search="restore health allies")
    protection = await search_spell(search="defensive barrier ward")

Hybrid search (search + filters):
    fire_evocation = await search_spell(
        search="fire explosion", school="evocation"
    )
    low_level_healing = await search_spell(
        search="heal wounds", level_max=3
    )

With test context injection (testing):
    from lorekeeper_mcp.tools.search_spell import _repository_context
    custom_repo = SpellRepository(cache=my_cache)
    _repository_context["repository"] = custom_repo
    spells = await search_spell(level=0)

Args: level: Exact spell level ranging from 0-9. 0 represents cantrips/0-level spells, 9 represents 9th level spells. Example: 3 for exactly 3rd level spells level_min: Minimum spell level (inclusive) for range-based searches. Use with level_max to find spells in a range. Returns spells at this level or higher. Examples: 1 for 1st level and above, 5 for 5th level and above level_max: Maximum spell level (inclusive) for range-based searches. Use with level_min to find spells in a range. Returns spells at this level or lower. Examples: 3 for up to 3rd level spells, 5 for up to 5th level spells school: Magic school filter for spell type. Valid values: abjuration, conjuration, divination, enchantment, evocation, illusion, necromancy, transmutation. Each school has distinct characteristics. Example: "evocation" for damage-dealing spells, "abjuration" for protective spells class_key: Filter spells available to a specific class. Valid values: wizard, cleric, druid, bard, paladin, ranger, sorcerer, warlock, artificer. Each class has access to different spell lists. Example: "wizard" for spells in wizard spell list concentration: Filter for spells requiring concentration. True returns only concentration spells, False returns only non-concentration spells. Concentration is a key resource in combat. Example: True ritual: Filter for ritual spells. Returns only spells that can be cast as rituals, allowing casting without expending spell slots. Example: True casting_time: Casting time filter to find spells with specific casting times. Examples: "1 action" (most common), "1 bonus action" (quick casts), "1 reaction" (reaction spells), "1 minute" (extended preparation) damage_type: Filter spells by damage type dealt. Examples: "fire" (fire damage), "cold" (cold damage), "necrotic" (necrotic damage), "poison" (poison damage), "psychic" (psychic damage). NEW in Phase 3. documents: Filter to specific source documents. Provide a list of document names/identifiers from list_documents() tool. Examples: ["srd-5e"] for SRD only, ["srd-5e", "tce"] for SRD and Tasha's. Use list_documents() to see available documents. search: Natural language search query for semantic/vector search. When provided, uses vector similarity to find spells matching the conceptual meaning rather than exact text matches. Can be combined with other filters for hybrid search. Examples: "fire damage explosion", "healing allies", "protection from evil creatures" limit: Maximum number of results to return. Default 20. Useful for pagination or limiting large result sets. Examples: 5 for small sets, 20 for standard, 100 for comprehensive results

Returns: List of spell dictionaries, each containing: - name: Spell name - level: Spell level (0-9) - school: Magic school - casting_time: How long the spell takes to cast - range: Spell range/area of effect - components: Required components (V/S/M) - material: Material component description (if applicable) - duration: How long the spell lasts - concentration: Whether spell requires concentration - ritual: Whether spell can be cast as a ritual - desc: Full spell description and effects - higher_level: Effect when cast at higher levels - classes: List of classes that can learn this spell - document__slug: Source document reference - damage_type: Damage types dealt by the spell (if applicable)

Raises: ApiError: If the API request fails due to network issues or server errors