build_change_actor

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

With no annotations, the description carries the full burden and does well by disclosing read-only behavior, the return shape ('returns { command }'), and per-kind input variants. It does not cover validation or error behavior, but for a command builder that is acceptable.

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 only two sentences and front-loads the purpose; each clause adds needed grouping or safety information. It avoids redundant restatement of schema fields and has no filler.

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 9-parameter tool with no output schema, the description covers return value, target types, and variant-specific required arguments. It leaves default flags like indent, showLevelUp, and allowKnockout to the schema, which is reasonable because the schema documents them.

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 the schema already describes every parameter (100% coverage), the description adds semantic grouping not present in the schema: hp/mp/exp/level use operand, state uses add/remove + stateId, and recover_all takes nothing extra. This helps the agent know which parameters apply to each kind.

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 ('Build') and resource ('actor stat-change scene command'), explicitly names the six command kinds (hp, mp, state, recover_all, exp, level), and states it is read-only. This clearly distinguishes it from sibling builder tools and event-command manipulators.

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 states the intended usage context ('for insertion via insert_event_commands') and enumerates all supported variants. It does not explicitly name alternative tools or exclusions, but the builder-for-insertion relationship is clear.

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