search_equipment

Search and retrieve D&D 5e weapons, armor, and magic items using the repository pattern.

This tool provides comprehensive equipment lookup across weapons, armor, and magical
items. Filter by rarity, damage potential, complexity, or attunement requirements.
Automatically uses the database cache through the repository for improved performance.

Examples:
    Basic equipment lookup:
        rare_items = await search_equipment(type="magic-item", rarity="rare")
        light_armor = await search_equipment(type="armor", is_simple=True)

    Using cost ranges (NEW in Phase 3):
        affordable_weapons = await search_equipment(
            type="weapon", cost_max=25
        )
        expensive_items = await search_equipment(
            type="weapon", cost_min=50, cost_max=100
        )

    Using weight and properties (NEW in Phase 3):
        lightweight_weapons = await search_equipment(
            type="weapon", weight_max=3
        )
        finesse_weapons = await search_equipment(
            type="weapon", is_finesse=True
        )
        light_dual_wield_weapons = await search_equipment(
            type="weapon", is_light=True
        )
        magical_weapons = await search_equipment(
            type="weapon", is_magic=True
        )

    Complex equipment queries:
        affordable_simple_weapons = await search_equipment(
            type="weapon", is_simple=True, cost_max=10
        )
        light_finesse_weapons = await search_equipment(
            type="weapon", is_light=True, is_finesse=True, limit=10
        )
        expensive_magical_weapons = await search_equipment(
            type="weapon", is_magic=True, cost_min=100
        )

    Searching all types:
        all_chain_items = await search_equipment(
            type="all", search="chain"
        )

    Semantic search (natural language queries):
        melee_weapons = await search_equipment(
            type="weapon", search="slashing blade for close combat"
        )
        protective_gear = await search_equipment(
            type="armor", search="heavy protective plate"
        )
        magical_storage = await search_equipment(
            type="magic-item", search="bag that holds items"
        )

    Hybrid search (search + filters):
        finesse_slashing = await search_equipment(
            type="weapon", search="elegant blade", is_finesse=True
        )
        rare_magical = await search_equipment(
            type="magic-item", search="fire wand", rarity="rare"
        )

Args:
    type: Equipment type to search. Default "all" searches all types. Options:
        - "weapon": Melee weapons (longsword, dagger, etc.) and ranged weapons (bow, crossbow)
        - "armor": Protective gear (leather armor, chain mail, plate, etc.)
        - "magic-item": Magical items (Bag of Holding, Wand of Fireballs, etc.)
        - "all": Search all equipment types simultaneously (may return many results)
    rarity: Magic item rarity filter (weapon/armor types don't use this).
        Valid values: common, uncommon, rare, very rare, legendary, artifact
        Example: "rare" for high-value magical items
    damage_dice: Weapon damage dice filter to find weapons dealing specific damage.
        Examples: "1d4" (dagger), "1d8" (longsword), "2d6" (greataxe), "1d12" (greatsword)
    is_simple: Filter for simple weapons (True) or martial weapons (False).
        Simple weapons: club, dagger, greatclub, handaxe, javelin, light hammer, mace,
        quarterstaff, sickle, spear
        Martial weapons: all other melee and ranged weapons
        Example: True for low-complexity options
    requires_attunement: Magic item attunement filter. Some powerful items require
        attunement to a character. Examples: "yes", "no", or specific requirements
    cost_min: Minimum cost in gold pieces (weapons and armor). Filters items costing
        at least this amount. Example: 10 for items costing 10+ gp
    cost_max: Maximum cost in gold pieces (weapons and armor). Filters items costing
        at most this amount. Example: 25 for items costing 25 gp or less
    weight_max: Maximum weight in pounds (weapons). Filters weapons weighing at most
        this amount. Example: 3 for lightweight weapons
    is_finesse: Finesse property filter (weapons). When True, returns only weapons
        with the finesse property (can use STR or DEX modifier). Example: True
    is_light: Light property filter (weapons). When True, returns only light weapons
        suitable for dual-wielding. Example: True

Returns:
    List of equipment dictionaries. Structure varies by type:

    For type="weapon":
        - name: Weapon name
        - damage_dice: Damage expression (e.g., "1d8")
        - damage_type: Type of damage (slashing, piercing, bludgeoning)
        - weight: Weight in pounds
        - is_simple: Whether this is a simple weapon
        - range: Range for ranged weapons (e.g., "20/60 feet")
        - properties: Weapon properties (finesse, heavy, reach, two-handed, etc.)
        - rarity: Equipment rarity

    For type="armor":
        - name: Armor name
        - armor_class: AC provided by this armor
        - armor_class_dex: Whether DEX bonus applies (light/medium)
        - armor_class_strength: Whether STR requirement applies (heavy)
        - weight: Weight in pounds
        - armor_category: Light/Medium/Heavy classification
        - rarity: Equipment rarity

    For type="magic-item":
        - name: Item name
        - description: What the item does and its powers
        - rarity: Rarity level (common through artifact)
        - requires_attunement: Attunement requirements
        - wondrous: Whether item is wondrous (non-weapon/armor)
        - weight: Weight if applicable
        - armor_class: AC bonus if armor
        - damage: Damage if weapon

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