list_capabilities

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

Even with readOnlyHint, idempotentHint, and destructiveHint already present, the description adds valuable behavioral context: setup fields and available_setup_adapters are informational-only in inventory mode, and 'Managed setup never executes a workload.' This meaningfully extends beyond the annotations and does not contradict them.

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: the first sentence states the core purpose, and the second sentence packages the important mode caveat and safety guarantee. Every sentence contributes necessary information with no redundant filler.

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?

Given the output schema and strong annotations, the description covers the critical behavioral distinction between inventory mode and scoped mode. The only omission is mode semantics, but the enum plus default and the tool's read-only nature reduce the risk, making the description complete enough for correct invocation.

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 description explains the adapter parameter well, including its omission semantics, which goes beyond the schema. However, the mode parameter has no description in the schema and is not addressed in the tool description, so the agent is left to infer the meaning of passive, active_cached, and active_refresh. With 50% schema coverage, the description only partially compensates.

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 names a specific verb ('List'), a concrete resource ('capabilities and setup actions'), and a clear scope ('scoped to a selected capture adapter'). It also clarifies the omit-adapter mode as a 'complete read-only inventory,' distinguishing the two calling patterns and separating this tool from setup-mutating siblings.

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 gives explicit direction on when to omit the adapter versus when to select one, including the instruction to call again before mutating the managed environment. It does not name alternative sibling tools explicitly, but the context tells an agent when the two modes are appropriate.

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