diagnose

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: it is a composite operation that gathers multiple data sources and returns a synthesized report with probable root cause and recommendations. It also discloses that the summarize parameter requires WATSONX_API_KEY, which is a useful environmental dependency. It does not detail failure modes or how the composite steps behave, but the annotations plus the composite description are adequate.

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 a single, information-dense sentence that front-loads the core purpose ('Composite diagnosis') and then lists the gathered components and output. Every clause earns its place; there is no filler or repetition of the tool name.

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 composite tool with no output schema, the description does a good job of explaining what the report contains (probable root cause and recommendations). It also covers the key input modes (alert_id vs device_name) and the optional summarize behavior. It does not specify the format of the diagnosis report or how detail_level affects the output, but the schema documents detail_level's enum and default, so the remaining gap is minor.

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 description coverage is 100%, so the schema already documents all four parameters. The description adds value by clarifying the relationship between alert_id and device_name (device_name 'finds most recent critical alert') and by explaining that summarize appends a plain-English NL summary via IBM Granite. This goes beyond the schema's field-level descriptions and helps an agent choose between the two mutually exclusive input modes.

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 states a specific composite verb ('diagnose') and resource ('alert or device'), and enumerates the exact components gathered (alert details, device context, correlated alerts, recent changes, blast radius, health score) plus the output (diagnosis report with probable root cause and recommendations). This clearly distinguishes it from siblings like get_alert_details, analyze_blast_radius, and score_device_health, which are single-purpose tools.

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 implies when to use it: when a composite diagnosis is needed, given an alert or device. It does not explicitly state when not to use it or name alternatives like get_alert_details or analyze_blast_radius, but the composite nature and the 'given an alert or device' input framing provide clear context. A small gap remains in not explicitly excluding single-purpose tools.

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