ise_update_deployment

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

No annotations are provided, so the description carries the full burden. It discloses key behaviors: partial updates ('Only the fields you pass change; everything else is preserved'), the reslug identity-change side effect ('moves its stored credentials'), and details about password preservation. It also explains TLS/CA trust behavior for ca_cert_path. Strong behavioral disclosure, though it doesn't cover every parameter's runtime behavior.

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 densely packed but every sentence earns its place. Each sentence delivers a distinct piece of guidance: what it does, partial-update semantics, reslug behavior, password exclusion and alternative, and error reporting. No wasted words or repetition.

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?

This is a complex tool with 21 parameters, no output schema, and zero annotations. The description addresses the key risks: partial updates, reslug/rename behavior, password handling, and TLS/CA behavior. It doesn't explain return value or error format fully ('Reports any remaining gaps' hints at output), but given the complexity, the description covers the most critical behavioral gaps well. Some param interactions (dataconnect variants) could be richer but the description is solid for the risk profile.

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 67%, and the description itself adds semantic value for several params: the reslug interplay with name change, ca_cert_path's explanation of httpx certifi behavior and the '' clear pattern, dataconnect_host's fallback behavior, dataconnect_os_trust's CA-store validation. The description adds meaning beyond the schema for many parameters, though the 33% uncovered params (dataconnect_sid, dataconnect_wallet_path, etc.) aren't explained in the description either.

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 opens with a specific action: 'Modify an EXISTING deployment's non-secret settings.' It clearly states the verb (modify/update), the resource (deployment), and scope (non-secret settings). It distinguishes from siblings by noting this is for existing deployments, complementing ise_add_deployment, and it explicitly differentiates from set-credential for password handling. Strong purpose clarity.

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 provides explicit guidance on when to use: fixing typos (wrong host) or adding information later (enable Data Connect). It explicitly says when NOT to use it for passwords ('Passwords are NEVER set here') and points to the alternative (terminal command). It also explains the reslug requirement clearly with guidance on what happens if not satisfied ('rejected with guidance'). This is exemplary usage guidance.

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