build_change_gold

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

With no annotations, the description carries the full burden. It explicitly states 'Read-only: returns { command }', disclosing that the tool does not mutate project state and what it returns. This is a useful behavioral disclosure beyond the schema, though it could further note that it only builds the command without inserting it (already implied) and may not validate operand-value consistency.

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 two sentences with no wasted words. The first sentence delivers the core purpose and the second adds the key behavioral trait (read-only) and return shape. It is well front-loaded and easily scannable.

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?

The tool has a nested operand object with conditional fields, no output schema, and no annotations. The description covers the main purpose, return shape, and read-only nature, but does not explain the conditional requirements of the operand sub-parameters (e.g., which fields are required based on type) or show an example output command structure. This leaves some gaps for correct invocation, but the simplicity of the operation and clear schema descriptions keep it adequate.

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 100% for all parameters, so the schema already documents operation (increase/decrease), operand type (constant/variable), value, and variableId. The description adds only a high-level summary ('increase or decrease party gold by a constant or variable amount') without clarifying conditional requirements (e.g., when type=variable, variableId is needed; when constant, value is needed). This matches the baseline of 3 for high schema coverage.

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 tool builds a specific Change Gold (125) event command, distinguishes it from the many other build_* tools (e.g., build_show_text, build_control_switch), and specifies its purpose of insertion via insert_event_commands. Verb 'build' plus resource 'Change Gold' gives a precise, unambiguous action.

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 explicitly situates this tool in the pipeline with 'for insertion via insert_event_commands', telling the agent when to use it (to generate a command before inserting). It does not explicitly name alternatives or exclusions, but the build_* family context plus the specific resource makes the appropriate use case clear.

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