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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, which cover safety aspects. The description adds behavioral context by explaining the data sources (GitHub PR metadata, Snyk vulnerability data) and the nature of outputs (root cause categories with confidence scores). This goes beyond the annotations without contradicting 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 three sentences, front-loaded with the primary purpose in the first sentence. It is concise, with no wasted words, and each sentence adds valuable information: what it does, how it does it, and when to use it.

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?

There is an output schema, so return values are covered elsewhere. The description provides a solid overview and clarifies some parameters, but it leaves gaps for snyk_org_id and time_range_days. Given the low schema coverage, more param detail would improve completeness.

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 only 20%, leaving most parameters undocumented. The description clarifies pr_url and incident_id by saying 'Inputs include GitHub PR URL or incident ID,' but it does not explain snyk_org_id or time_range_days. It partially compensates for the schema gap but not fully.

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 classifies root causes of change failures, which is a specific verb and resource. It further distinguishes itself by mentioning the use of GitHub PR metadata and Snyk vulnerability data, and outputs like structured root cause categories with confidence scores. This makes it distinct from sibling tools focused on other incident metrics.

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 provides clear usage context by stating it is 'Ideal for post-mortem analysis and change risk assessment.' It also implies the tool is used when inputting a GitHub PR URL or incident ID. However, it does not explicitly name alternatives or when not to use the tool, so it falls short of a 5.

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