add_event_command

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

With no annotations, the description carries the full burden. It discloses key behaviors: indent must increase by 1 inside branch blocks, the trailing code-0 terminator is preserved automatically, and choice branches must stay in sync. These are non-obvious behavioral details that help the agent avoid errors. It doesn't mention error handling or reversibility, but the provided details are substantial.

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 dense but every sentence adds value: the main action, the alternative for Show Text, a practical code reference, and two critical structural rules. It's a single paragraph without fluff, though the code list is long. The most important information is front-loaded.

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 of the tool (nested command object, many code types), the description provides a comprehensive reference for common codes and structural rules. It does not explain return values or error handling, but the absence of an output schema suggests simple success/failure responses. The 'position' parameter is covered in the schema. Overall, it's sufficient for a well-informed agent.

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 coverage is only 20%, so the description compensates by explaining the `code` parameter in detail with a list of common XP codes and their specific parameter structures (e.g., 102=Show Choices, 123=Control Self Switch). It also explains `indent` semantics. The other parameters (mapId, eventId, pageIndex) are self-evident from the tool name, and `position` is described in 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 opens with a clear verb and resource: 'Add a single command to an event page'. It immediately differentiates itself from the sibling tool add_show_text by stating 'for Show Text prefer add_show_text', showing the agent exactly which tool to use for that specific case.

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 guidance to prefer add_show_text for Show Text commands, and offers a detailed list of common XP codes with their meanings and structural requirements (e.g., indent, branch blocks, terminator). While it doesn't explicitly mention when not to use this tool for other event operations, the purpose and code list make the context clear.

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