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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value beyond annotations by explaining the tool's behavior: it compares inputs to national benchmarks and flags upcoding risk (as shown in the example). It also discloses data source (CMS and OIG composite), which is useful behavioral context.

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 usage guidance and output summary. The example is compact and illustrative. No redundant language; every sentence earns its place.

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?

For a simple read-only tool with 3 optional parameters and no output schema, the description covers usage, outputs, a worked example, and data source. The only notable gap is the lack of explicit parameter explanations for annual_claim_volume, but the example covers most of the input semantics. Overall, sufficiently complete for an agent to invoke it correctly.

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 33% (one property described). The description partially compensates by illustrating parameters through the example: 'Cardiology practice E/M mix at 67% level 4/5 visits' clarifies specialty and level_4_5_percentage. However, annual_claim_volume is not explained anywhere, and the description does not systematically map parameters to their roles.

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 what the tool does: 'Returns E/M distribution benchmarks, upcoding risk signals, OIG audit priority themes, and RAC watchlist.' This goes beyond a simple verb+resource by listing specific outputs and providing a concrete example, making it distinctive from sibling benchmark tools.

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 opens with when to use the tool: 'Use when assessing coding compliance risk before an OIG audit, preparing for a RAC review, or building a revenue integrity program.' While it doesn't name alternatives, the use cases are specific enough to guide selection. Missing exclusions (when not to use) but strong context.

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