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

Beyond the readOnly/idempotent annotations, the description discloses real behavioral detail: bot and dependabot PRs are excluded from the outcome comparison, first-party reports override inference for the same PRs, the result self-reports when samples are too small or detection hasn't covered the period, and the attribution block grades inferred attribution error rates. That is exactly the caveat context an agent needs before trusting or quoting the numbers.

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?

It front-loads the business question and the returned metrics, then layers caveats in decreasing importance. It is dense but nearly every clause carries information; the attribution paragraph is the longest and slightly buries its point, but is still relevant and not redundant with the schema or annotations.

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 an output schema present, the description needn't restate return shapes, and it correctly spends its words on interpretation and caveats instead: sample-size warnings, detection coverage gaps, bot exclusion, and attribution confidence. For a two-optional-parameter read tool with full annotations, nothing material is missing.

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%, and the schema itself carries the important nuance (the repository slug resolves team scope but does not filter metrics; period enum defaults to rolling_30d). The description adds no period semantics or hints about choosing between rolling vs calendar windows, so it sits at the baseline rather than adding value.

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 names a specific question and then enumerates exactly what the tool returns: adoption rate, contribution intensity, AI-assisted PR rate, detected tools, detection confidence, and an outcome split on lead time and size. This clearly distinguishes it from adjacent siblings such as get-mcp-adoption-tool (MCP-specific) and report-ai-usage-tool (ingestion rather than reporting).

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?

It gives concrete intent framing — answer "is AI actually in our SDLC yet" and "is it paying off" with one call — and positions the outcome split as the KPI-grade signal versus adoption as a pilot metric. It also flags interaction with report-ai-usage-tool for first-party reports. What it lacks is an explicit exclusion, e.g. when to prefer get-mcp-adoption-tool or the DORA/PR metric tools instead.

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