update_namespace

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

Discloses patch semantics, the no_changes response when all fields are omitted, immediate application with no dry run or undo, and the success result shape. These behaviors go well beyond the annotations, which only provide hints that the operation is a non-read-only, non-idempotent, non-destructive write. No contradiction with annotations exists.

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 compact and front-loaded with the action and target. Each sentence contributes distinct value: patch behavior, no-op response, immediacy/no-undo, sibling differentiation, and parameter sourcing. No filler or redundancy.

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?

For a 5-parameter mutation tool with no output schema, the description covers what is updated, how updates are applied, what happens when no fields are passed, what the success response looks like, and where to find valid values. The absence of an output schema is mitigated by the explicit return shape in the description.

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 coverage is 100%, so the schema already explains each parameter. The description adds meaningful context by clarifying that passing no optional fields produces no_changes without an API call, and by pointing to list_supervisor_storage_policies as the source for valid storage_policy values. This elevates it above the baseline.

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?

Description opens with a specific verb and resource: 'Update resource quotas or storage policy of an existing vSphere Namespace.' It clearly distinguishes from the sibling create_namespace by stating to use this when the namespace exists. The [WRITE] marker reinforces that this is a mutating operation.

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?

Explicitly says 'Use this rather than create_namespace when the namespace exists,' giving an unambiguous when-to-use rule with a named alternative. It also advises where to get valid storage_policy values, which is actionable guidance for selecting and preparing the call.

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