mc_dig

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

With no annotations, the description carries the full burden and does substantial work: it discloses automatic tool switching ('会自己换成对的工具'), that results include the `held` item, a hard ~11s execution ceiling, that a partial run returns a 'time budget exhausted' message, and that dug blocks are retained in inventory so partial calls aren't wasted. Missing only failure modes (block not found, out of `maxDistance`, invalid coordinates).

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?

Front-loads the two targeting modes, then the time-budget constraint before the re-call instruction. The repetition of the 11-second limit is deliberate emphasis on the one constraint that most affects correct invocation, and nothing else is padding.

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 6-parameter mutation tool with no annotations and no output schema, the description covers the essential runtime model: how targeting works, the per-call time cap, continuation semantics, tool auto-switching and the `held` result field. The remaining gap is the un-bundled x/y/z alternative and unstated error behavior, which leaves it just short of fully self-sufficient.

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 33% — only `count` and `maxDistance` are documented in the schema. The description meaningfully compensates for `name` (nearest match) and reinforces `count`, but `x`, `y`, and `z` have no coverage anywhere, and the description never states that the three coordinates must be supplied together as an alternative to `name`.

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 a specific verb and resource (dig blocks) plus the two selection modes — by `name` for the nearest matching block, or by `pos` for an exact coordinate — and notes that `count` repeats the action. It is unmistakable what the tool does, though it never names or contrasts a sibling tool (e.g. mc_move, mc_scan) to sharpen the boundary.

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?

Gives clear operating context: pick `name` for nearest-match digging or coordinates for a specific target, and use `count` with a re-call loop for bulk work. The 10–11 second per-call budget and the explicit 'just call mc_dig again to continue' instruction are strong practical guidance, but there is no statement of when NOT to use it or which sibling to prefer instead.

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