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

Beyond the annotations, it discloses critical runtime behavior: Midi-QOL rolls and applies HP, fastForward skips dialogs, awaiting_user_dialog is not an error and must not be retried, and appliedDamage/appliedHealing report per-token results. It also warns against modeling one-off circumstances as effects because effects hit every copy of an unlinked token. No contradiction with annotations; the description substantially enriches the behavioral picture.

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 text is dense but almost every clause carries operational value, and the core purpose is front-loaded before the edge-case guidance. It could be easier to scan if split into short bullets, but it is not padded or repetitive. Minor readability cost keeps it from a 5.

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?

For a complex 17-parameter tool with no output schema, the description covers the important gaps: output semantics (appliedDamage/appliedHealing, applied false), dialog/status behavior, AoE coordinate conventions, target requirements, and the sibling alternative. Nothing essential for correct invocation appears to be missing.

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?

Although schema coverage is already high at 88%, the description adds cross-parameter meaning and pitfalls: targetTokenIds is for attacks, attackMode/ammunition/consume answer fastForwarded dialogs, attackerTokenId selects among multiple tokens, and templatePosition uses a pixel formula. It also clarifies how one-off modifiers should be supplied instead of effects. This is well beyond what the schema alone conveys.

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 opens with a specific verb and resource: 'Activate an item with full Foundry automation (Midi-QOL hooks, targets, AoE templates): attacks, spells, abilities.' It explicitly distinguishes this from the quick-use sibling by ending with 'dnd5e-item-use is the quick use without targets.' An agent can tell exactly what this tool does and when it differs from the simpler alternative.

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?

It gives explicit routing rules: use targetTokenIds for attacks, use dnd5e-apply-damage when applied is false, and use dnd5e-item-use for quick use without targets. It also explains how to encode one-off circumstances via advantage/disadvantage, attackBonus, damageBonus, and targetAcBonus rather than creating effects. This is about as strong as usage guidance gets.

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