mark_moved

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It says nothing about whether an existing location is overwritten, whether a move_history entry is appended, what happens if the item name is unknown, or whether the write is reversible. For a mutation tool with zero annotation coverage, this is a significant gap. The only behavioral detail given is the container-only case.

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 purpose is front-loaded in one sentence, followed by compact per-parameter lines with useful examples. The wording is tight and there is no filler. Small blemishes: the parenthetical "(new drawer, newbox, new shelf, new box)" is redundant, and "newbox" is a typo.

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?

An output schema exists, so return values do not need explanation. However, for a four-parameter mutation with no annotations, the description should clarify write semantics (overwrite versus history append) and error behavior on an unknown item. As written, it is adequate for constructing the call but thin on consequences.

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%, with only bare titles, so the description must compensate. It documents item (name or ID, with an example), new_room (current room, plus the container-only case) and note (optional 'why', with an example). new_container is only referenced obliquely as something that can change while the room stays the same, and its relationship to new_room is left to inference. This is reasonable but incomplete compensation.

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 and resource: "Record that an item moved". That makes it distinguishable from siblings such as add_item, remove_item and where_is at first glance. It does not name any sibling explicitly, so there is no stated differentiation.

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 guidance "keep the same room with a different new_container if it only changed containers" is a concrete usage rule for a real ambiguity, which is better than nothing. However, there is no statement of when to prefer this tool over siblings, no prerequisites such as the item needing to exist, and no exclusions. Usage has to be inferred.

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