Manage items

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

Annotations already signal destructive intent and mark the operation as non-read-only, but the description adds concrete behavioral details: folders are created when missing and named in the answer, item types are checked before anything is written, actor removal needs the 'full' permission, and exact-name matches that hit multiple items are refused. There is no contradiction with 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?

The tool definition is dense and front-loaded with the domain, and each semicolon-separated clause covers one action without wasted wording. The single run-on structure is harder to scan than bullets, but it is appropriately sized for six actions and contains 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 six-action, nine-parameter tool with no output schema, the description covers action semantics, permission requirements, ambiguity handling, and validation-before-write behavior. It does not explicitly state return shapes for list/update/remove/add-to-actor, though the action names and schema make those reasonably inferable.

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?

The input schema already documents all parameters with 100% coverage, so the baseline is 3. The description adds value beyond the schema by explaining action-dependent usage, the pre-write game-system type check, and the behavior of a created folder's name being included in the answer.

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 'Items in the world and on actors' and then defines each action with a clear verb and resource: 'create' makes world items, 'remove-from-actor' deletes actor items, and 'describe' returns valid item types. It is specific within the tool, but it does not explicitly contrast with sibling tools such as manage-actors, create-document, or system-specific item tools, so differentiation from alternatives is implicit rather than stated.

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 gives clear usage context for every sub-action: 'list' filters, 'update' changes by id, 'remove-from-actor' requires full actor permission and refuses ambiguous name matches, and 'describe' reports valid types. It does not mention alternative tools to prefer instead of this one, leaving the sibling choice largely left to the agent's inference.

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