Add an item to a category

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 does disclose a key behavior: linking an existing item makes it shared, and 'editing it later updates every category it appears in.' However, it does not explain other important behaviors like how fields are treated when existingItemId is provided (e.g., ignored or applied), or what response to expect. There is useful context but significant gaps remain.

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, well-structured sentence that front-loads the primary action and uses a parenthetical to explain the alternative. It is concise and does not waste words, though the dense length might benefit from splitting into clearer conditions.

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?

With 13 parameters, no annotations, and no output schema, the description leaves too much unspecified. It covers the main dual-mode behavior but omits details about parameter interplay, required fields for new items, edge cases, and return values. The tool is complex enough that a richer description is needed for reliable use.

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 the role of existingItemId, leaving the other 12 parameters without semantic explanation. The schema provides names and types but no descriptions, and the tool description does not clarify how parameters like qty, price, or weight are used in the two modes. This is under-compensated for a 13-parameter tool.

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 states the tool's function: 'Adds a new item to a category' and also explains a second mode for linking an existing item via existingItemId. This is a specific verb+resource pair and distinguishes this tool from siblings like add_items_batch by covering the single-item vs. shared-item use case.

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 provides some usage context by explaining the two modes ('Adds a new item' vs. 'if existingItemId is given — links an already-existing item'), but it does not explicitly compare to alternatives (e.g., add_items_batch, update_item) or state when to choose this tool over them. Usage is implied rather than explicit.

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