Send a chat message

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

Annotations only indicate non-readOnly and non-idempotent, so the description carries the burden. It discloses that unknown or ambiguous names cause the message to be sent to nobody, that content is HTML (implying rendering), and that default speaker/behaviors are based on actor/token. This adds significant behavioral context beyond annotations.

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 concise, with two sentences that front-load the core function and the most critical caveat (visibility). It avoids redundancy and includes the HTML note efficiently. Every sentence provides essential information.

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?

With 9 parameters and no output schema, the description covers essential behavioral context like visibility rules, recipient failure, and content format. It doesn't explain return values, but that's minor since chat messages typically don't need complex return handling. The absence of output schema is compensated adequately.

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 includes 100% parameter descriptions, so baseline is 3. The description adds a few nuances (e.g., recipient resolution failure, exact name matching) but mostly reiterates schema details. It does not use the available space to further clarify edge cases like speakerToken UUID format beyond 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 it posts a message to Foundry chat as the Gamemaster or as an actor/token, with specific behavioral details. It distinguishes this from related tools like list-chat-messages or update-chat-message by focusing on sending new messages.

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?

Provides explicit condition for public vs private messages ('Without whisperTo and whisperToGamemasters everyone sees it'), and warns about potential failure ('an unknown or ambiguous name sends nothing'). While it doesn't name siblings, the clear scoping to chat sending is sufficient, and the warning about recipient resolution helps avoid errors.

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