it_ops_detect_waste

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is available structurally. The description adds useful routing context (domain-agent dispatcher, JWT, tenant, company scope), but it does not explain what resources the action may modify or delete, which would have added meaningful transparency beyond the annotations.

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, front-loads the action, and uses a clear Args block without filler. It loses a point because the brevity comes at the expense of behavioral and usage detail, but the structure itself is clean and scannable.

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?

With 0% schema coverage, a destructive action, and a very large sibling list, this description leaves an agent guessing what detect_waste actually does and when to call it. The output schema covers return values, but selection criteria, expected input structure, and behavioral consequences are not sufficiently described.

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 0%, so the description is the only source of parameter meaning. It labels message as a free-text objective and inputs as an optional JSON string of structured inputs, which is genuinely informative but still underspecified—there are no examples, key names, or explanation of how message and inputs relate.

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 first sentence names the action (detect_waste) and says it is run through the it_ops domain agent, but it never says what detecting waste actually does—e.g., analyze cloud spend, find underutilized resources, or propose cleanup. This mostly restates the tool name, and it does not distinguish the tool from sibling it_ops tools like it_ops_analyze_cost or it_ops_rightsizing_recommendations.

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?

There is no guidance on when to use this tool versus alternatives, no mention of what kinds of waste-detection objectives are appropriate, and no exclusions or prerequisites beyond JWT/tenant/company scope. The phrase 'free-text objective' implies any waste-detection request, but the description does not help an agent choose this tool over related IT operations tools.

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