Gives a specified item to the player during the update phase and reports storage counts before and after, including quest letters.
Give the player an item (update phase) and report the before/after count in the player's storage. Works for every category incl. quest letters (verified with Torn Letter 376, 2026-10-26).
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| item_id | Yes |
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It does disclose the mutation effect and the return shape ("report the before/after count in the player's storage"), plus the update-phase timing and a verified edge case, but says nothing about permissions, additive stacking behavior, or what happens on failure.
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?
Two tight sentences, with the core action front-loaded ahead of edge-case scope. The verification anecdote ("Torn Letter 376, 2026-10-26") is somewhat noisy for an agent but does convey tested coverage.
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?
Output schema exists, so return format needn't be spelled out, and the description does mention before/after counts. But for a two-param mutation tool with no annotations and zero schema descriptions, it should at minimum tell the agent where item_id comes from and whether count is additive.
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% and neither parameter is mentioned in the description — not item_id (an integer with no stated source such as dd2_items), nor count (defaulted to 1, with no statement of whether it adds to the existing stack). This is the definition's largest gap.
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?
Names a specific verb and resource ("Give the player an item") and adds scope via "(update phase)", which distinguishes it from read-only siblings like dd2_items or dd2_recent_items. It stops short of naming a sibling explicitly, so it is clear but not fully differentiated.
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 scope note "Works for every category incl. quest letters" tells the agent this is a general-purpose item granter rather than a category-specific one, which is useful selection guidance. However there is no explicit when-not or pointer to an alternative tool for inspecting item IDs or inventory, so usage must be inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.