rpg-mcp

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

With no annotations provided, the description carries the full burden. It mentions that auras 'move with their owner and affect targets within radius' and 'optionally requires concentration,' adding some behavioral context. However, it omits critical details like whether this is a mutation (implied by 'Create'), what happens on failure, if it interacts with other systems (e.g., process_aura_effects), or the response format, leaving significant gaps.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by additional context. It's efficient with two sentences, but could be slightly more structured by explicitly separating usage notes from behavioral traits.

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

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

Given the complexity (12 parameters, no output schema, no annotations), the description is incomplete. It lacks details on return values, error conditions, interactions with sibling tools (e.g., process_aura_effects), and comprehensive behavioral context, making it inadequate for a mutation tool with many parameters in a game system.

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

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

Schema description coverage is high at 92%, so the baseline is 3. The description adds minimal value beyond the schema by hinting at radius usage ('within radius') and concentration, but doesn't explain parameter relationships (e.g., how effects array interacts with triggers) or provide examples for complex fields like effects, relying heavily on the schema.

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

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

The description clearly states the specific action ('Create a new aura effect') with the resource ('centered on a character'), provides concrete examples (Spirit Guardians, Aura of Protection), and distinguishes it from sibling tools by focusing on aura creation rather than management (e.g., remove_aura, get_active_auras).

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

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

The description implies usage for creating auras in a game context with examples, but lacks explicit guidance on when to use this tool versus alternatives (e.g., apply_custom_effect for non-aura effects) or prerequisites like character existence. It mentions concentration optionally, which hints at context but isn't comprehensive.

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