item_add

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

With no annotations, the description carries the transparency burden. It discloses meaningful behavioral traits: items are atomic, titles/descriptions are bounded, gates are required, and gate_timeout_ms defaults to 5000 with null disabling it. It does not discuss output or failure behavior, but it goes well beyond a bare 'add item' statement.

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 a single, front-loaded sentence that packs essential constraints and a parameter default without redundancy. Every phrase adds information, and there is no filler or repetition of the tool name.

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 8 parameters, nested gate objects, no annotations, and no output schema, yet the description only touches a few aspects. It omits the meaning of subsprint, code_locations, gates, dependencies, and high_priority, and gives no indication of return values or side effects. This is not complete enough for reliable autonomous invocation.

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%, so the description must compensate. It only explains gate_timeout_ms semantics and vaguely references 'bounded' titles/descriptions; dependencies, high_priority, subsprint, code_locations, and gates are left undefined. This is insufficient for correctly understanding and constructing all parameters.

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 identifies the action ('Add') and resource ('atomic item'), and the phrase 'bounded title, bounded description, code locations, gates' distinguishes this creation tool from siblings like item_update, item_done, or item_deprecate. It communicates enough about the item type to make the tool's purpose unambiguous.

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 conveys that this tool is for adding new atomic items and explicitly lists required components, but it does not state when to prefer this tool over alternatives or provide exclusion criteria. Usage context is implied by the name and sibling set, not explicitly guided.

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