roll_check
Roll D&D 5e skill checks, ability checks, saving throws, attack rolls, and initiative for your character during RPG sessions.
Instructions
Roll D&D 5e checks including skill checks, ability checks, saving throws, attack rolls, and initiative
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| characterId | No | ||
| characterName | No | ||
| checkType | Yes | ||
| skill | No | ||
| ability | No | ||
| dc | No | ||
| advantage | No | ||
| disadvantage | No | ||
| bonus | No | ||
| contestedBy | No | ||
| contestedCheck | No |
Implementation Reference
- src/modules/characters.ts:1528-1614 (handler)Main handler function executing roll_check logic: validates input, loads character if specified, performs d20 rolls with advantage/disadvantage/proficiency, handles skill/ability/save/attack/initiative checks, supports contested checks and DC evaluation, returns formatted ASCII markdown output.export function rollCheck(input: RollCheckInput): { success: boolean; markdown: string; error?: string; } { // Validate check-specific requirements if (input.checkType === 'skill' && !input.skill) { return { success: false, markdown: '', error: 'skill is required for skill checks', }; } if ((input.checkType === 'ability' || input.checkType === 'save' || input.checkType === 'attack') && !input.ability) { return { success: false, markdown: '', error: `ability is required for ${input.checkType} checks`, }; } // Load character if provided let character: Character | undefined; if (input.characterId || input.characterName) { const charResult = getCharacter({ characterId: input.characterId, characterName: input.characterName, } as any); if (!charResult.success || !charResult.character) { return { success: false, markdown: '', error: charResult.error || 'Character not found', }; } character = charResult.character; } // Handle contested checks separately if (input.contestedBy && input.contestedCheck) { return handleContestedCheck(input, character); } // Perform the roll using helper function const rollResult = performRoll(input, character); if (!rollResult.success) { return { success: false, markdown: '', error: rollResult.error, }; } const result = rollResult.result; // Evaluate DC if provided let dcResult: 'success' | 'failure' | undefined; if (input.dc !== undefined) { dcResult = evaluateDCResult(input.checkType, result.naturalRoll, result.total, input.dc); } // Format output const markdown = formatCheckResult({ checkType: input.checkType, checkName: result.checkName, character: character?.name, abilityKey: result.abilityKey, abilityMod: result.abilityMod, profMod: result.profMod, bonusMod: result.bonusMod, totalMod: result.totalMod, rollMode: result.rollMode, rolls: result.rolls, naturalRoll: result.naturalRoll, total: result.total, dc: input.dc, dcResult, }); return { success: true, markdown, }; }
- src/modules/characters.ts:152-171 (schema)Zod input schema for roll_check tool defining parameters like checkType, skill/ability, DC, advantage/disadvantage, bonus, and optional contested check.export const rollCheckSchema = z.object({ characterId: z.string().optional(), characterName: z.string().optional(), checkType: z.enum(['skill', 'ability', 'save', 'attack', 'initiative']), skill: SkillSchema.optional(), ability: AbilitySchema.optional(), dc: z.number().optional(), advantage: z.boolean().optional(), disadvantage: z.boolean().optional(), bonus: z.number().optional(), contestedBy: z.string().optional(), contestedCheck: z.object({ type: z.enum(['skill', 'ability']), skillOrAbility: z.string(), }).optional(), });
- src/registry.ts:442-465 (registration)Tool registration in central registry: defines name, description, converts schema to JSON Schema for MCP, provides wrapper async handler that validates input with rollCheckSchema and delegates execution to rollCheck function.roll_check: { name: 'roll_check', description: 'Roll D&D 5e checks including skill checks, ability checks, saving throws, attack rolls, and initiative', inputSchema: toJsonSchema(rollCheckSchema), handler: async (args) => { try { const validated = rollCheckSchema.parse(args); const result = rollCheck(validated); if (!result.success) { return error(result.error || 'Failed to roll check'); } return success(result.markdown); } catch (err) { if (err instanceof z.ZodError) { const messages = err.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', '); return error(`Validation failed: ${messages}`); } const message = err instanceof Error ? err.message : String(err); return error(message); } }, },