D&D 5e SRD Oracle

Apply Character Operation

apply_character_session_operation

Destructive

Update a D&D character outside battle: adjust equipment, gain levels, manage companions or forms, apply healing or rests, track recovery time, and spend or convert resources.

Instructions

Update a finalized character outside Battle: change equipment or levels, manage forms and companions, apply healing or rests, advance recovery time, or spend and convert resources. Choose one operation.kind and its matching fields; every affected Character Session must be available in this Play Session. Returns character state and, when applicable, an operation result; calendar-time recovery may request dice fills. Changes can consume resources and are not safe to repeat blindly. Use query_character_session for read-only projections, creation tools for drafts, and Battle tools for in-Battle actions.

Input Schema

TableJSON Schema

Name	Required	Description
`operation`	Yes	Choose exactly one kind and provide that variant's fields. Use setEquipmentLoadout for equipment, advanceClassLevel for advancement, the form or companion kinds for retained selections, healing or rest kinds for recovery, passCalendarTime for elapsed-time recovery, and resource kinds to spend or convert uses. For an interrupted Long Rest, submit every interruption segment and the final completion together with strictly increasing cumulativeRestedTicks; no intermediate rest is retained. All referenced characters must belong to this Play Session and be available outside Battle.
`characterId`	Yes	Character Session id from finalize_character or list_characters in this Play Session. The character must be available outside Battle; for healing operations this is the source character.
`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.

Changed2 schema fields changedv0.1.1Sep 21, 2026

addedInput schema / properties / characterId / description

Added value: +"Character Session id from finalize_character or list_characters in this Play Session. The character must be available outside Battle; for healing operations this is the source character."

addedInput schema / properties / operation / description

Added value: +"Choose exactly one kind and provide that variant's fields. Use setEquipmentLoadout for equipment, advanceClassLevel for advancement, the form or companion kinds for retained selections, healing or rest kinds for recovery, passCalendarTime for elapsed-time recovery, and resource kinds to spend or convert uses. For an interrupted Long Rest, submit every interruption segment and the final completion together with strictly increasing cumulativeRestedTicks; no intermediate rest is retained. All referenced characters must belong to this Play Session and be available outside Battle."

First observedSep 21, 2026

TDQS

A4.7/5.0

Behavior4/5

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

Annotations already carry destructiveHint=true and readOnlyHint=false, and the description adds a concrete warning that changes consume resources and are not safe to repeat blindly. It also discloses the return shape and the dice-fill possibility for calendar-time recovery, going beyond the structured annotation data.

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?

Five sentences, front-loaded with the core update action, then prerequisites, return behavior, safety warning, and sibling routing. Every sentence earns its place, and the prose is remarkably compact for a tool with such a large schema.

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

Completeness5/5

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

Given the large union schema, rich annotations, and output schema, the description supplies the missing operating context: finalized/outside-Battle precondition, Play Session availability, one-kind selection rule, return behavior, dice-fill possibility, and non-idempotence. An agent has enough information to decide and invoke this tool correctly.

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

Parameters4/5

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

Schema description coverage is 100%, so the schema carries most parameter semantics; the description adds a useful grouping of operation kinds by intent ('setEquipmentLoadout for equipment, advanceClassLevel for advancement...') and stresses choosing exactly one kind with matching fields. It also calls out the non-obvious interrupted-long-rest segment submission behavior.

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

Purpose5/5

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

States a specific verb and resource ('Update a finalized character outside Battle') and enumerates the kinds of state changes: equipment, levels, forms/companions, healing/rests, recovery time, and resource spend/convert. It also distinguishes from sibling groups by pointing to query, creation, and Battle tools.

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

Usage Guidelines5/5

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

Explicitly limits use to finalized characters outside Battle and requires affected Character Sessions to be available in the Play Session. It names alternatives: query_character_session for read-only projections, creation tools for drafts, and Battle tools for in-Battle actions, giving clear when-not-to-use guidance.

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