audit_trigger_health

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

Annotations provide readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable behavioral detail: it tolerates per-kind upstream errors with notes in the output, and a missing trigger list is fatal. This gives the agent important context on error handling 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 two sentences and front-loaded with the list of checks. It is concise but includes a bold phrase that, while emphasizing usage, could be considered slightly redundant. Overall, it is well-structured and efficient with minimal wasted words.

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 no output schema, the description adequately explains the report's contents (specific anomaly types) and notes that errors are listed in a 'notes' field. However, it does not detail the format or structure of the output, leaving some ambiguity. For a composite report tool, it is mostly complete but could be more explicit about return value organization.

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 coverage is 100% with the two parameters (refresh, instance) already described. The description does not add any additional meaning for these parameters beyond what is in the schema. According to the guidelines, baseline 3 is appropriate when schema coverage is high and description adds no extra param info.

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 clearly states it is a composite trigger-hygiene report listing specific checks (conflicts, deactivated but referenced, orphaned references, ordering anomalies, empty rules). It distinguishes itself from siblings like find_trigger_conflicts by noting it bundles multiple checks in one call, making the purpose explicit and unique.

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 explicitly positions this as 'the right starting point for trigger cleanup work,' indicating it is a comprehensive first step. While it does not list specific alternatives or when not to use it, the context is clear and implies using this over individual check tools for an overall health report.

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