D&D 5e SRD Oracle

Fill Battle Hole

fill_battle_hole

Destructive

Resolve a missing battle action detail by submitting the required fill for a selected subject, letting the session advance its combat state.

Instructions

Fill one hole for a selected battle act subject. MCP retains the base session, subject, and accepted fills while the battle runtime advances the checkpoint/frontier envelope.

Input Schema

TableJSON Schema

Name	Required	Description
`fill`	Yes	Build one fill object from the current returned hole, preserving its kind and holeId. For an attack targetChoice, use the branch identified by hole.attack.selection: Character attacks require attackAbility and attackDamageType and omit statBlockDamageSelection; Stat Block attacks require the complete statBlockDamageSelection and omit attackAbility and attackDamageType. Copy actorId from hole.attack.actorId and the branch fields from hole.attack.selection. For a ranged spell target hole whose spellTargetSpatialFactRequest.requiresExactDistance is true, include one spellTarget fact with distanceFeet set to the exact caster-to-target distance. A chained Spell Attack leap hole also requires the spellLeapTargetWithinRange fact named by spellLeapTargetSpatialFactRequest. Include a rangedSpellAttackEnemyProximity fact for each adjacent visible, non-Incapacitated enemy, even when the selected target is an ally or a distant creature. The server validates the complete fill against the canonical battle contract.
`subject`	Yes	Copy the exact subject object returned by discover_battle_acts or the preceding needsHoles result.
`playSessionId`	Yes	Play Session handle returned by create_play_session for follow-up stateful calls in the same local process or authenticated account.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedSep 21, 2026

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes beyond the destructiveHint annotation by stating that MCP retains the base session, subject, and accepted fills while the battle runtime advances the checkpoint/frontier envelope. It reveals that the call mutates battle state and preserves prior fills, which is useful context not present in the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is only two sentences: the first states the operation, the second gives the most important state-retention and side-effect context. It is front-loaded and contains no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The rich input schema (including exact subject-copy instructions and fill construction rules) and output schema cover most invocation details, so the short description is sufficient to accompany them. It lacks explicit workflow ordering or alternative routing, but the parameter and output schemas largely compensate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already fully documents all three parameters. The tool description itself adds no parameter-level detail beyond referring to 'accepted fills,' so it earns the baseline 3 rather than more.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'Fill one hole for a selected battle act subject.' This clearly places it in the battle-act workflow and distinguishes it from the sibling fill_creation_holes through the 'battle act subject' qualifier, though it does not explicitly name that alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The intended use is implied: fill one hole after a battle act subject is selected. There is no explicit when-to-use/when-not-to-use guidance or named alternative, though the phrases 'selected battle act subject' and 'accepted fills' suggest the surrounding discover-and-fill workflow.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.