Suggest Solutions

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely non-obvious behavior: it defaults to mining resolved incidents, and out-of-range max_solutions values are clamped and reported rather than rejected — useful for predicting call outcomes.

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?

Front-loaded with the core purpose, then a scannable WHEN TO USE list, then argument-cap mechanics. Minor waste in marketing phrasing ('KEY for incident response', 'For training new responders on resolution patterns'), but nothing structurally confusing.

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?

Return values are covered by the output schema and safety by annotations, and the description fills in the call-selection and clamping behavior. It leaves 'similar' undefined and does not say what happens when neither incident_id nor title/description yields matches, a minor gap for a 5-parameter tool.

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?

With only 40% schema description coverage, the description compensates well: it explains the incident_id vs. title/description alternative, states the max_solutions <= 10 cap and clamp behavior, and clarifies the resolved-by-default status behavior. It does not explain status_filter's empty-string-for-all option, which only appears in 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?

States a specific verb and resource ('Get actionable solution recommendations from similar resolved incidents') and scopes it to incident response. It is clearly distinguishable from the nearest sibling find_related_incidents, which surfaces related incidents rather than resolution steps.

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 WHEN TO USE block gives four concrete triggering situations and explicitly sequences the tool after find_related_incidents, which is strong contextual guidance. It stops short of stating when NOT to use it (e.g., unresolved incidents with no history), so it lands at 4 rather than 5.

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