gateway_update

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

Annotations already signal that this is a mutating operation (readOnlyHint=false). The description adds valuable behavioral nuance by stating that only provided fields are updated and that supplying tags replaces the entire tag map. It does not cover auth or error behavior, but the annotation baseline lowers the burden.

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 the core purpose and a necessary side-effect warning. No wasted words.

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 essential purpose and the main side effect, and the output schema handles return values. However, with 8 parameters and no schema descriptions, it leaves gaps around null semantics, field units, and failure behavior, making it adequate but not fully complete.

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 adds the key partial-update rule and the specific tags-replacement behavior, which is the most non-obvious parameter semantic. However, most parameters get no individual explanation, and null-clearing behavior is not clarified.

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 states a specific verb and resource: 'Update only the given fields of a gateway.' This clearly distinguishes it from sibling tools like gateway_create, gateway_get, gateway_list, and gateway_delete.

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 'Update only the given fields' makes the intended use case clear: modifying an existing gateway without replacing the whole object. It does not explicitly name alternatives or exclusion conditions, but the context is unambiguous enough for an agent to select it appropriately.

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