search_character_option
Search for D&D 5e classes, races, backgrounds, and feats. Use natural language queries or filter by source document to find character creation options.
Instructions
Retrieve D&D 5e character creation and advancement options.
This tool provides access to classes, races, backgrounds, and feats for character creation and level-up decisions. Each option type provides different information relevant to character building. Results are cached for faster repeated lookups through the repository pattern.
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: Default usage (automatic repository creation): classes = await search_character_option(type="class") elves = await search_character_option(type="race", search="elf") backgrounds = await search_character_option(type="background", search="soldier") feats = await search_character_option(type="feat", search="great")
With test context injection (testing):
from lorekeeper_mcp.tools.search_character_option import _repository_context
custom_repo = CharacterOptionRepository(cache=my_cache)
_repository_context["repository"] = custom_repo
classes = await search_character_option(type="class")
Semantic search (natural language queries):
warriors = await search_character_option(
type="class", search="martial combat warrior"
)
sneaky_classes = await search_character_option(
type="class", search="stealthy shadow assassin"
)
magical_races = await search_character_option(
type="race", search="innate magical abilities"
)
Hybrid search (search + filters):
srd_fighters = await search_character_option(
type="class", search="melee fighter", documents=["srd-5e"]
)Args: type: REQUIRED. Character option type. Must be one of: - "class": Player classes (Barbarian, Bard, Cleric, Druid, Fighter, Monk, Paladin, Ranger, Rogue, Sorcerer, Warlock, Wizard) - "race": Playable races (Human, Elf, Dwarf, Halfling, Dragonborn, Gnome, Half-Orc, Half-Elf, Tiefling, etc.) - "background": Character backgrounds (Acolyte, Criminal, Entertainer, Soldier, Folk Hero, Sage, etc.) - "feat": Character feats (Ability Score Improvement, Great Weapon Master, Magic Initiate, etc.) - typically chosen at levels 4, 8, 12, 16, 19 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 character options matching the conceptual meaning rather than exact text matches. Can be combined with other filters for hybrid search. Examples: "martial combat warrior", "stealthy rogue", "divine magic healer" limit: Maximum number of results to return. Default 20, useful for limiting output or pagination. Examples: 1, 5, 50
Returns: List of option dictionaries. Structure varies by type:
For type="class":
- name: Class name
- hit_dice: Hit die value (1d8, 1d10, 1d12)
- class_levels: Progression table
- spellcasting: Spell slots if applicable
- features: Class features by level
For type="race":
- name: Race name
- ability_score_increase: Ability score bonuses
- age: Aging information
- alignment: Typical alignments
- size: Size category
- speed: Movement speed
- languages: Known languages
- traits: Racial traits and special abilities
For type="background":
- name: Background name
- skill_proficiencies: Skill choices
- tool_proficiencies: Tools (if any)
- feature: Special background feature
- personality_traits: Suggested personality options
- ideals: Suggested ideals
- bonds: Suggested character bonds
- flaws: Suggested character flaws
For type="feat":
- name: Feat name
- description: Feat benefits and requirements
- ability_score_increase: Ability bonuses (if any)
- prerequisites: Requirements to take featRaises: ValueError: If type parameter is not one of the valid options ApiError: If the API request fails due to network issues or server errors
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | ||
| limit | No | ||
| search | No | ||
| documents | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |