ise_list_deployments

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

With no annotations provided, the description carries the full behavioral burden. It discloses that the return includes credential status ('whether credentials are set'), which is a useful safety-relevant detail. However, it doesn't disclose whether this read operation could fail, whether credentials are actually shown or just a boolean flag, or any pagination/limits. Given it's a simple list operation, the transparency is adequate but not rich.

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 sentences, compact and informative. The first sentence states the purpose and return fields; the second explains downstream usage. Slightly verbose example text ('e.g. List RADIUS policy sets on Deployment 1') but otherwise efficient. No wasted sentences.

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 zero-parameter, no-output-schema listing tool, the description covers the essential value: what it lists, what fields are returned, and how to use the results. It's a simple enumeration operation, so the description is reasonably complete. It could mention whether it sorts or filters, but for a plain list tool this is sufficient.

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 tool has zero parameters, so semantic explanation of parameters is moot. The description uses the space to clarify how the tool's output (number/name) becomes a parameter value for other tools, which effectively serves the same purpose as parameter documentation by explaining the tool's role in the broader invocation flow.

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+resource ('List every configured ISE deployment') and clearly enumerates what fields are returned (number, name, slug, host, credentials set). It differentiates from siblings by establishing this as the enumeration tool for deployments, distinct from the individual getter tools (ise_get_deployment) and the setup tools (ise_set_default_deployment, ise_add_deployment, etc.).

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 explicit guidance on when to use this tool: 'Call this to see what is available.' It also instructs the agent to use the returned number/name in any tool's 'deployment' argument, directly showing how the output feeds into other tool invocations. This makes the usage context and downstream relevance clear.

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