npm_update_stream

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

The description adds one behavioral trait: partial update semantics ('Provide only fields to change'). With no annotations, this is useful, but it leaves out other behavioral aspects like authorization, return value, or side effects.

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 short sentences, front-loaded with action, no filler. Every word contributes value.

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 description covers the basic operation and partial update rule, but lacks information about return values, error handling, or prerequisites, which is important for a 7-param update tool with no output schema or annotations.

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 description provides a general rule for parameter usage: only fields to change should be supplied, making all optional parameters PATCH-style. However, it does not explain individual parameter meanings, though schema property names are self-descriptive.

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 'Update' with a clear resource 'existing stream', distinguishing it from sibling tools like create_stream or delete_stream. It directly states the action and scope.

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 clearly indicates the tool is for modifying an existing stream, which is distinct from creating or deleting. It does not explicitly name alternatives, but the context is clear from the sibling list and the instruction to provide only changed fields.

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