ise_add_deployment

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

No annotations provided, so description carries full burden. It discloses passwords are NEVER passed here, that it returns terminal command(s) for setting passwords afterward, and reports every missing/invalid field at once. It doesn't state whether the operation is reversible (could be removed via ise_remove_deployment) or whether it requires special auth, but the key behavioral traits (secrets handling, batch validation, return format) are covered.

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?

Well-structured with a leading summary sentence, then a GUIDED FLOW block with numbered decision prompts. Each sentence earns its place. Slightly over the line in length given the guided-flow detail, but the structure (summary + numbered guide) aids quick scanning and is arguably necessary given the complexity.

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?

Very complex tool (20 params, 2 required, no output schema) yet coverable via description: the return format is specified (terminal commands for password), the validation behavior is stated, the certification decision tree is fully enumerated. The only minor gap is no explicit statement about whether this is idempotent or what happens on duplicate name, but overall this is complete for a tool of this complexity.

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 80%, and several params have rich descriptions (ca_cert_path explaining certifi/OS trust behavior, verify_ssl explaining MITM implications, dataconnect_os_trust explaining cert handling). The description adds critical cross-parameter context about dataconnect_cert_path vs dataconnect_os_trust tradeoffs and dataconnect_host-by-default behavior not fully in the schema. Description complements rather than duplicates the schema.

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?

Clear verb+resource: 'Add a new ISE deployment to the registry'. Distinctly differentiates from siblings (ise_list_deployments, ise_update_deployment, ise_remove_deployment, ise_set_default_deployment) by establishing it's the creation operation. Also clarifies it handles non-secret fields and returns password-setting commands, which no sibling mentions.

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?

Provides an explicit GUIDED FLOW section telling the agent to gather optional surfaces by asking the user rather than assuming. Gives concrete decision branches (Data Connect vs ERS API, same node vs separate MnT, self-signed vs CA-signed cert, MAPI vs DC preference). This is exemplary guidance on when and how to use vs alternative options like monitoring_enabled vs dataconnect.

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