Set item externalId

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

The description discloses that this is a write operation ('Write') and adds a behavioral guarantee ('without touching other fields'). The annotations already provide idempotentHint and destructiveHint, so the description complements rather than contradicts them, giving context beyond the structured metadata.

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 sentence that is front-loaded with the primary action and scope. The additional 'Write.' is concise and avoids unnecessary detail, making it efficient.

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?

Given the simple tool with only 3 parameters, no output schema, and annotations covering safety, the description is largely complete. It clearly states what is updated and the scope, but could arguably mention response format or error behavior; however, that is not essential for this simplicity.

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 has 100% description coverage for all parameters, so the baseline is 3. The description does not add additional parameter semantics beyond what the schema already states, but it does confirm the purpose of 'externalId' as a link to the system's record.

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 uses a specific verb ('Set or change') and clearly identifies the resource ('the externalId of an item') and scope ('only', 'without touching other fields'). This distinguishes it from the broader update_item sibling by emphasizing the partial update.

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 phrase 'without touching other fields' provides clear context that this should be used when the external ID is the only field to update, implying that other fields should be left untouched. It does not explicitly name an alternative like update_item, but the guidance is sufficiently clear.

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