建造逐格藍圖

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false. The description adds a non-obvious behavioral trait: identical blocks are automatically merged into the fewest possible fill commands, which affects execution cost and expectations. It does not contradict annotations. This extra context is valuable beyond the 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?

Two sentences, front-loaded with the primary action and input format, and the sibling routing is placed second. No redundant phrasing; every clause earns its place.

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?

Description plus schema and annotations cover what the tool does, when to use it, how input is structured, and the destructive/idempotent behavior. An output schema exists, so return values are accounted for. The only small gap is whether coordinates are absolute or relative, but Minecraft tool conventions and the plain integer schema make absolute coordinates the likely default, so this is not a serious omission.

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 0%, but the description compensates by framing the sole parameter (entries) as a 'coordinate → block' list, which maps directly to the array of position/block pairs. It does not spell out the JSON structure or the optional blockStates, but the schema already provides those details, and the semantic framing is enough for an agent to form the correct input shape.

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?

States '蓋出任意形狀' (build any shape) with a specific verb and resource, and immediately clarifies the input mechanism (coordinate→block list). It explicitly contrasts with sibling mc_build_shape, which is for geometric shapes, and lists its intended use cases (pixel art, text, irregular shapes, external data), so an agent can distinguish it from alternatives.

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?

Explicitly names the alternative tool mc_build_shape and gives a routing rule: prefer it for geometric shapes, use this for pixel art/text/irregular/external data. This is a clear when-to-use/alternative statement with no ambiguity.

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