docs(tools): enhance skill check and math_manage descriptions

- math_manage: Redirect skill/ability/save checks to specialized tools
- roll_skill_check: Document auto-calculation of proficiency, expertise,
  armor stealth disadvantage
- roll_ability_check: Document auto-calculation of ability modifier
- roll_saving_throw: Document auto-calculation of save proficiency,
  note that combat saves are handled by combat_action

All three skill check tools now clearly marked as PREFERRED over math_manage.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: Mnehmos

src/server/consolidated/math-manage.ts

@@ -297,18 +297,21 @@ export const MathManageTool = {
     name: 'math_manage',
     description: `Mathematical operations for RPG mechanics.
 
-⚠️ COMBAT REDIRECT - DO NOT USE FOR:
-- Attack rolls → Use combat_action { action: "attack" } instead
-- Spell damage → Use combat_action { action: "cast_spell" } instead
-- Saving throws in combat → combat_action handles these automatically
-The combat_action tool rolls dice, calculates damage, and applies HP changes in one call.
-
-🎲 DICE ROLLING (roll) - For NON-COMBAT situations:
-- Skill checks outside combat
+⚠️ REDIRECT - DO NOT USE FOR:
+- Attack rolls → Use combat_action { action: "attack" }
+- Spell damage → Use combat_action { action: "cast_spell" }
+- Skill checks → Use roll_skill_check (auto-applies proficiency)
+- Ability checks → Use roll_ability_check (auto-applies modifier)
+- Saving throws → Use roll_saving_throw (auto-applies save proficiency)
+
+These specialized tools look up character stats and apply bonuses automatically!
+
+🎲 DICE ROLLING (roll) - Use ONLY for:
 - Stat generation (4d6dl1)
 - Random tables/loot
-- NPC behavior rolls
-- Exploration/navigation
+- NPC behavior/morale rolls
+- Weather/random encounters
+- Anything without character stat bonuses
 
 Standard notation plus special modifiers:
 - 2d6+3: Basic roll with modifier

src/server/skill-check-tools.ts

@@ -94,8 +94,17 @@ function getAbilityModifier(abilityScore: number): number {
 export const SkillCheckTools = {
     ROLL_SKILL_CHECK: {
         name: 'roll_skill_check',
-        description: `Roll a skill check using character stats. Automatically applies ability modifier and proficiency bonus if proficient.
-Example: roll_skill_check with characterId and skill="perception" for active character's Perception check.`,
+        description: `Roll a skill check using character stats. PREFERRED over math_manage for skill rolls!
+
+🎯 AUTO-CALCULATES:
+- Ability modifier from character stats
+- Proficiency bonus if character is proficient
+- Expertise (double proficiency) if applicable
+- Armor stealth disadvantage (automatically detected)
+
+Skills: perception, stealth, athletics, acrobatics, arcana, history, investigation, nature, religion, animal_handling, insight, medicine, survival, deception, intimidation, performance, persuasion, sleight_of_hand
+
+Example: { characterId: "abc123", skill: "perception", dc: 15 }`,
         inputSchema: z.object({
             characterId: z.string().describe('ID of the character making the check'),
             skill: SkillEnum.describe('Skill to roll (e.g., perception, stealth, athletics)'),
@@ -108,7 +117,14 @@ Example: roll_skill_check with characterId and skill="perception" for active cha
 
     ROLL_ABILITY_CHECK: {
         name: 'roll_ability_check',
-        description: 'Roll a raw ability check (no skill proficiency). Uses only the ability modifier.',
+        description: `Roll a raw ability check (no skill proficiency). PREFERRED over math_manage!
+
+🎯 AUTO-CALCULATES:
+- Ability modifier from character stats
+
+Use for: Initiative, grapple contests, raw strength/dex tests
+
+Example: { characterId: "abc123", ability: "str", dc: 12 }`,
         inputSchema: z.object({
             characterId: z.string().describe('ID of the character making the check'),
             ability: AbilityEnum.describe('Ability score to use (str, dex, con, int, wis, cha)'),
@@ -121,7 +137,16 @@ Example: roll_skill_check with characterId and skill="perception" for active cha
 
     ROLL_SAVING_THROW: {
         name: 'roll_saving_throw',
-        description: 'Roll a saving throw. Applies proficiency bonus if character has save proficiency.',
+        description: `Roll a saving throw. PREFERRED over math_manage for saves!
+
+🎯 AUTO-CALCULATES:
+- Ability modifier from character stats
+- Proficiency bonus if character has save proficiency
+
+Use for: Trap saves, environmental hazards, out-of-combat saves.
+Note: In-combat spell saves are handled automatically by combat_action cast_spell.
+
+Example: { characterId: "abc123", ability: "dex", dc: 14 }`,
         inputSchema: z.object({
             characterId: z.string().describe('ID of the character making the save'),
             ability: AbilityEnum.describe('Saving throw type (str, dex, con, int, wis, cha)'),

tmpclaude-46d4-cwd

@@ -0,0 +1 @@
+/f/Github/mnehmos.rpg.mcp

tmpclaude-68e9-cwd

@@ -0,0 +1 @@
+/f/Github/mnehmos.rpg.mcp